@1aboveio/skills 0.15.0 → 0.17.0

package/skills/payment/fraud-analysis/references/workflow.md

@@ -0,0 +1,175 @@
+# Fraud-analysis workflow (steps 0–9)
+
+Called from [SKILL.md](../SKILL.md). Paths below are relative to the skill root.
+
+## 0 — Pre-flight
+
+Inspect the input, requested target, and label provenance before planning a
+supervised analysis. Record:
+
+```yaml
+label_provenance: file-column | user-defined | absent
+positive_definition: ""
+negative_definition: ""
+unlabeled_definition: ""
+preflight_status: pass | needs-user-input | descriptive-only | blocked
+```
+
+- Confirm the file is readable and identify its row grain, candidate time field,
+  outcome/label fields, and requested positive definition.
+- When the positive label comes from an existing row-level outcome column, map
+  its positive value(s). Assume the rest of the mature analysis population is
+  negative, except explicit missing, pending, unknown, or unlabeled states.
+  State this assumption and show the observed values to the user when ambiguous.
+- When the user defines the positive label as a condition or derived rule,
+  require the user to define the negative condition during pre-flight. Do not
+  infer `NOT positive` as negative. Ask one focused clarification and set status
+  to `needs-user-input` until answered.
+- Rows matching neither class, both classes, explicit unknown states, or an
+  immature outcome window are unlabeled.
+- If no usable positive and negative definitions exist, offer descriptive
+  segmentation without precision/recall, or block supervised analysis.
+
+Do not proceed to the supervised workflow until pre-flight passes. A
+`descriptive-only` analysis may select a profile and explore segments, but it
+must not compute precision, recall, lift, or supervised strategy performance.
+Profile clarification may be grouped into the same user question when both
+label and attribution inputs are missing.
+
+## 1 — Select analysis profile
+
+Read [taxonomy.md](taxonomy.md). Record:
+
+```yaml
+archetype: third-party-fraud | first-party-fraud | authorized-payment-scam | unclassified
+customer_role: victim | perpetrator | knowing-participant | facilitator | unknown
+customer_consent: present | absent | disputed | unknown
+technical_authentication: passed | failed | not-applicable | unknown
+mechanisms: []
+contexts: []
+subtype: null
+attribution_confidence: confirmed | probable | proxy | unknown
+event_grain: ""
+decision_point: ""
+```
+
+- Select exactly one primary archetype. Select one or more mechanisms and
+  contexts when the data supports them.
+- Customer consent and technical authentication are separate facts. Passed
+  login, MFA, or session checks do not prove genuine-customer consent.
+- `APP scam` is a subtype of `authorized-payment-scam` in a `bank-transfer`
+  context; it is not a synonym for first-party fraud.
+- If victimization versus knowing participation is unresolved, use
+  `unclassified`. Do not silently force attribution.
+- If multiple archetypes are confirmed, run separate labels, rules, metrics,
+  and impact sections. Never blend them into one positive class.
+
+Read the selected archetype, mechanism, and context references before Step 2.
+
+## 2 — Formalize label
+
+- One primary label per archetype analysis. Confirmed outcomes are ground truth;
+  proxies must be identified as proxies.
+- Carry forward the pre-flight provenance and class definitions; do not discover
+  the negative class here.
+- Validate the pre-flight mapping against observed rows and record the resulting
+  positive, negative, and unlabeled counts.
+- If the mapping is incomplete or contradictory, return to pre-flight with
+  `needs-user-input`; do not ask for or invent a negative class in this step.
+- Derive labels only from supplied data and documented business meaning. Positive
+  and negative conditions must be disjoint. Rows matching neither, both, or an
+  immature/pending state are unlabeled and excluded from supervised metrics.
+- Record positive definition/count, negative definition/count, unlabeled
+  definition/count, base rate among labeled rows, maturity window, exclusions,
+  and attribution confidence.
+- Exclude the label, synonyms, investigations, recalls, disputes, or other later
+  outcomes from features when unavailable at the selected decision point.
+- For delayed outcomes, ensure enough observation time or mark recent rows as
+  immature rather than negative.
+- Do not continue to precision, recall, or supervised rule scoring until both
+  positive and negative classes are defined.
+
+## 3 — Freeze temporal validation
+
+- Freeze the cut before feature work. Train is earlier; holdout is later.
+- Do not random-shuffle rows or use random k-fold as headline validation.
+- History and graph snapshots contain prior events only.
+- No time column means full-sample descriptive analysis; mark metrics
+  **unvalidated**.
+
+## 4 — Engineer candidates
+
+Read [feature-engineering.md](feature-engineering.md) and all selected
+profile packs.
+
+- Declare event grain and decision point before assessing columns.
+- Classify fields as allowed now, excluded for zero variance, excluded for
+  timing, excluded for leakage, or context-only.
+- Build thresholds, rate lists, graph lists, and watchlists on train only.
+- Prefer interpretable conditions with explicit units and windows.
+- Do not invent columns, identity links, consent, intent, or actor attribution.
+
+## 5 — Select shortlist
+
+Use train only: lift, support, stability, operability, and meaningful
+interactions. Keep tiny or attribution-uncertain spikes for monitoring.
+
+## 6 — Score rules
+
+State explicit conditions, event grain, units, windows, and decision point.
+Headline holdout metrics use this order:
+
+**occurrence → precision → recall**
+
+Train metrics are debugging evidence only. If outcomes are value-bearing, also
+measure captured positive amount without replacing count-based metrics.
+
+## 7 — Map actions and packages
+
+Use actions from the selected context packs; there is no universal 3DS action.
+
+| Metric and evidence profile | Shared guidance |
+|---|---|
+| High precision, stable, severe impact | Consider the context's strongest preventive action |
+| Higher recall, moderate precision | Add verification, review, warning, hold, or friction |
+| Weak, unstable, small-N, uncertain attribution | Monitor or investigate |
+
+- Legal, regulatory, policy, and operational authority constrain account holds,
+  freezes, rejects, beneficiary blocks, and reporting.
+- Keep individual rules separate from multi-rule **strategy packages**.
+- Freeze default and comparison packages before report writing.
+- For each package compute triggered count/rate and amount/share, then precision
+  and recall, plus the context-specific customer, operations, conversion, delay,
+  and loss measures required by its pack.
+
+## 8 — Write business report
+
+Read [report-template.md](report-template.md),
+[terminology.md](terminology.md), and selected profile packs.
+
+Use reader order:
+
+执行摘要 → 抽样、分析画像与标签 → 规则发现 → 策略整体影响 → 特征 → 附录
+
+- Include the analysis profile and actor attribution near the start.
+- Report only domain-appropriate actions, denominators, and impact KPIs.
+- Strategy impact always includes count/rate and amount/share, then precision
+  and recall. Add only the selected contexts' required impact measures.
+- Do not present scenario estimates or proxy-label value as measured loss saved.
+- Save to a path such as `reports/fraud-analysis/<scope>.md`.
+- Before finishing: grep the report for banned strings in
+  [terminology.md](terminology.md) and fix language only (not numbers,
+  BIN lists, or thresholds).
+
+## 9 — Independent review
+
+Read [review-checklist.md](review-checklist.md) and selected packs.
+
+- Review the common method and presentation contract.
+- Apply checks from every selected archetype, mechanism, and context pack.
+- Auto-fix mechanical issues only. Do not silently change attribution, label,
+  customer role, or action severity.
+- Prefer a fresh independent reviewer. If unavailable, use a fresh same-session
+  checklist and disclose that only in the chat delivery note.
+- Deliver the business report plus a short note with verdict, fixes, and open
+  judgment issues. Keep review process details out of the report.

package/skills/payment/payment-analysis/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/payment/payment-analysis/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: payment-analysis
+description: >
+  Produce a visualized payment overview from authorization + settlement
+  extracts (optional chargebacks): executive summary, top statistics, payment
+  journey Sankey, and topics (volume, WoW trend, auth rate, BIN-country
+  contribution, decline-by-reason, decline-by-country). Amounts report in USD
+  (Forex Service daily conversion). Chargebacks use Visa same-month and
+  Mastercard lagged 拒付率. 运营影响 is 3DS / 风控拦截 / soft-decline retry
+  only. Use whenever the user asks for payment overview, auth-rate analysis,
+  decline mix, BIN/issuer-country contribution, settlement GMV, payment journey,
+  Sankey funnel, FX-to-USD, chargeback rate, 运营影响, or "business analysis of
+  transactions" — even if they do not say payment-analysis. Do NOT use for
+  supervised fraud-rule mining (that is fraud-analysis).
+---
+
+# Payment Analysis
+
+Descriptive payment-funnel analytics with charts. Explains what happened in the
+book. Does not invent fraud rules or claim loss saved.
+
+Use authorization **and** settlement when both files exist. Chargebacks are
+optional topic fuel, not required for the journey core.
+
+| Layer | Typical file | Row grain |
+|---|---|---|
+| Authorizations | `Authorizations_*.csv` | one auth attempt |
+| Settlements | `Sales-and-refunds_*settlements*.csv` | one sale or refund |
+| Chargebacks | `Chargebacks_*.csv` | one dispute (optional) |
+
+**Produce:** Markdown + preferred Chinese/bilingual HTML under
+`reports/payment-analysis/`.  
+**Do not produce:** supervised precision/recall packages (`fraud-analysis`).
+
+Read the playbook for the step you are on. Paths under `references/` are
+relative to this skill.
+
+## Workflow
+
+Follow these steps in order.
+
+### 0 — Pre-flight
+
+Read [event-layers.md](references/event-layers.md). Record layers present and
+missing, paths, time fields, currencies, and which journey checkpoints have
+usable columns. Amount reporting is USD: read [fx.md](references/fx.md) before
+any amount KPI (all-USD books still write `金额均为 USD` and do not call Forex).
+
+### 1 — Window and segments
+
+Freeze the analysis window (defaults in event-layers.md). Segment by BIN
+country, card product, response message/code, settlement type when present.
+
+### 2 — KPIs
+
+Compute auth + settlement metrics from [metrics.md](references/metrics.md).
+Convert non-USD amounts per [fx.md](references/fx.md) before any sum or share.
+If chargebacks are present, monthly 拒付率 follows
+[chargebacks.md](references/chargebacks.md) (Visa same-month, Mastercard lagged,
+skip empty brand-months, no blended Visa+Mastercard ratio).
+
+### 3 — Journey Sankey
+
+Build **count** flows with [journey.md](references/journey.md). Join sales to
+approved auths on `Order ID`. Footnote unjoined refunds. Skip risk/3DS nodes
+when authentication fields are empty; caption the skips.
+
+### 4 — Write outputs
+
+Structure and chapter minima:
+[report-template.md](references/report-template.md). Chart marks:
+[visualization.md](references/visualization.md). English/Chinese terms:
+[terminology.md](references/terminology.md). 运营影响 only from
+[auth-rate-actions.md](references/auth-rate-actions.md) when the extract
+supports the trigger.
+
+```text
+reports/payment-analysis/<scope>_overview.md
+reports/payment-analysis/<scope>_overview.zh.md
+reports/payment-analysis/<scope>_overview.zh.html
+```
+
+HTML is preferred when there are charts. Glossary applies to headings, KPI
+labels, legends, and Sankey skip chips.
+
+### 5 — Language proofread
+
+Grep every report file for the banned strings in
+[terminology.md](references/terminology.md). Replace hits using that table.
+Do not change numbers, joins, or chart data.
+
+### 6 — Sanity check
+
+- [ ] Structure is summary → top stats → Sankey → topics → 运营影响
+- [ ] Auth + settlement both used when both files exist
+- [ ] Sankey skips unavailable risk/3DS checkpoints and says so
+- [ ] Count/amount are bars; rate is a line; dual axes when combined
+- [ ] Amount axes/legends include currency (`授权尝试金额 USD`, …)
+- [ ] No supervised fraud-rule metrics
+- [ ] Non-USD amounts converted per fx.md; all-USD books say 金额均为 USD
+- [ ] Chargeback monthly rates skip empty brand-months; no blended Visa+MC ratio
+- [ ] 运营影响 only from auth-rate-actions.md when triggered
+- [ ] Language matches terminology.md; banned strings have no unexplained hits
+
+## Boundary with fraud-analysis
+
+| Need | Skill |
+|---|---|
+| Volume, journey Sankey, auth rate, decline mix, settlement overview, 运营影响 routing | `payment-analysis` |
+| Proxy/confirmed fraud labels, holdout precision/recall, 3DS/block **packages** | `fraud-analysis` |
+
+Routing 3DS / 风控拦截 / retry from this extract is not a fraud-analysis rule
+package.
+
+## Reference index
+
+| Need | Read |
+|---|---|
+| Grains, joins, windows | [event-layers.md](references/event-layers.md) |
+| USD conversion | [fx.md](references/fx.md) |
+| KPI formulas | [metrics.md](references/metrics.md) |
+| Visa / Mastercard 拒付率 | [chargebacks.md](references/chargebacks.md) |
+| Sankey checkpoints | [journey.md](references/journey.md) |
+| Chart marks | [visualization.md](references/visualization.md) |
+| Report chapters | [report-template.md](references/report-template.md) |
+| 运营影响 | [auth-rate-actions.md](references/auth-rate-actions.md) |
+| Language / banned strings | [terminology.md](references/terminology.md) |

package/skills/payment/payment-analysis/references/auth-rate-actions.md

@@ -0,0 +1,30 @@
+# Actions that often lift auth rate
+
+Use this list when writing **运营影响**. Pick only items the extract
+supports. Do not dump the whole list. These are routing / retry operations,
+not a `fraud-analysis` rule package (no precision/recall, no “loss saved”).
+
+Auth rate = 授权成功 / 授权尝试. BIN country = 发卡行国家.
+
+| # | When the data shows | Action | Do not write |
+|---|---|---|---|
+| 1 | BIN countries under SCA (e.g. UK, Spain, Italy) and Authentication method is empty / None | Route **3DS** for those 发卡行国家 | 强客户认证 as the standing term (use SCA); claiming 3DS will raise conversion |
+| 2 | A country (or book) where 疑似欺诈 is a large share of 授权拒绝 | **风控拦截** and/or **3DS** on that 发卡行国家 | Calling 疑似欺诈 “confirmed fraud”; putting this in the 3DS 与风控 exec slot as a decline mix |
+| 3 | Material **软性拒绝** (issuer soft: 余额不足, Do not honor, 超限, …) | **Retry** the authorization (same or later attempt, per acquirer retry rules) | Treating 无效卡 / 账户关闭 as retry-eligible |
+| 4 | 余额不足, 安全码无效, 有效期无效, Do not honor 等可解释的拒绝 | On the **payment page**, show the matching reason (余额不足 / 安全码错误 / 有效期错误), not a generic “支付失败” | Inventing copy the issuer did not return; hiding the reason |
+
+## How to cite in the report
+
+One short 运营影响 bullet per action, with the evidence already in the
+report (country, share, 软性拒绝 count). Example shapes:
+
+- SCA：英国、西班牙、意大利受 SCA 约束，当前分析时段内无 3DS，建议对这些发卡行国家路由 3DS。
+- 疑似欺诈：某国疑似欺诈占授权拒绝 X%，建议风控拦截或 3DS。
+- 软性拒绝：软性拒绝 N 笔（余额不足 / Do not honor / …），可按收单行规则重试。
+- 支付页提示：余额不足、安全码无效、有效期无效应在支付页给出对应提示，便于用户换卡或改卡号、有效期、安全码。
+
+## Out of scope
+
+- Supervised thresholds, holdout, 3DS/block “packages” → `fraud-analysis`
+- Inventing retry counts or expected auth-rate lift
+- Mixing portfolio and merchant grains in one file

package/skills/payment/payment-analysis/references/chargebacks.md

@@ -0,0 +1,88 @@
+# Chargeback / dispute rate (Visa vs Mastercard)
+
+Topic **4.8 拒付 / 争议**. Put the Visa / Mastercard formulas as a **note
+under the monthly rate chart**. Count rates follow card-network monitoring
+programmes, **not** origination-month vintage and **not** a blended
+Visa+Mastercard ratio.
+
+Official Visa and Mastercard rulebooks are acquirer-gated. The formulas
+below are the processor restatements used in production monitoring
+(Stripe, Braintree). Caption the report as **network-style estimates
+from this extract**, not as a Visa/Mastercard identification notice.
+
+## When a point is drawn
+
+A monthly point for a card brand is drawn **only if**
+
+- numerator (chargebacks **received** that calendar month for that brand) > 0, and
+- denominator (sales count for that brand, month as defined below) > 0.
+
+Otherwise **omit the point**. Do not plot `0`. Do not invent a prior-month
+sale count. If a brand has no drawable points, omit the series. If no
+series remain, omit the rate chart (keep the reason-category bars if CBs
+exist).
+
+## Formulas (count)
+
+Numerator for both brands: chargebacks **received** in calendar month `M`
+(`Chargeback date`), `Payment method` = that brand. Not original
+transaction month. Inquiries / RDR-cleared cases are not in this extract;
+count every CB row.
+
+| Brand | Programme (current) | Rate |
+|---|---|---|
+| Visa | VAMP dispute/sales count (same month) | `CB_Visa(M) / Sales_Visa(M)` |
+| Mastercard | ECP / ECM chargeback rate (lagged sales) | `CB_MC(M) / Sales_MC(M−1)` |
+
+`Sales_*` = settlement type Sale, that brand, **transaction/capture month**.
+Do not mix refunds into the denominator.
+
+Mastercard **must** use the previous calendar month’s sales. If `M−1`
+sales are missing from the extract, skip Mastercard for month `M`.
+
+## Visa notes (do not over-claim VAMP)
+
+Since 2025-04 Visa folded VDMP/VFMP into **VAMP**. Full VAMP Count is
+`opened Visa chargebacks (TC15) + reported fraud (TC40 EFW)`, same-month
+sales in the denominator. This skill’s extract usually has chargebacks
+only → report **Visa 拒付率 = Visa CB count / Visa same-month sales**.
+Do not label it “VAMP ratio” unless TC40/EFW is in the file.
+
+VAMP also has volume and enumeration legs; those are out of scope here.
+
+## Mastercard notes
+
+ECP (ECM / HECM) uses **both** a count threshold and the lagged rate.
+This report draws the **rate** series only. Do not say the merchant is
+“in ECM” from the extract.
+
+EFM is a different (fraud-reason + 3DS mix) programme; do not substitute
+it for ECP.
+
+## Amount rate (optional footnote)
+
+`abs(dispute amount) / sale amount` with the **same month alignment as
+the count rate** for that brand. Secondary; the line chart is count %.
+
+## Window caveat
+
+A short extract (e.g. 22 days of August plus a handful of July sales)
+cannot produce a Mastercard lagged rate for August unless July Mastercard
+sales exist, and cannot produce Visa July if July CBs are absent. Follow
+the skip rules; do not pad.
+
+## Sources
+
+- Stripe, *Dispute and fraud card monitoring programs*: Visa uses
+  disputes/fraud vs **same-month** payments; Mastercard uses
+  disputes/fraud vs **previous-month** payments; both assign the CB to
+  the month it was **received**.
+  https://docs.stripe.com/disputes/monitoring-programs
+- Braintree, *Visa Acquirer Monitoring Program (VAMP)*: VAMP ratio =
+  VAMP Count / **same-month** Visa sales count
+  (example: August count / August sales).
+  https://developer.paypal.com/braintree/articles/risk-and-security/card-brand-monitoring-programs/visa-programs/visa-dispute-monitoring-program
+- Chargebacks911 primer on Mastercard ECM rate: chargebacks in the
+  **current** month / Mastercard transactions in the **previous** month
+  (April 10,000 sales and May 90 CBs → May rate 1%).
+  https://chargebacks911.com/mastercard-chargebacks/mastercard-excessive-fraud-chargeback-monitoring-programs/mastercard-ecm-program-how-to-calculate-your-mastercard-chargeback-rate/

package/skills/payment/payment-analysis/references/event-layers.md

@@ -0,0 +1,79 @@
+# Event layers, grains, and joins
+
+## Layers
+
+| Layer | Example filename pattern | Default grain | Usual time field |
+|---|---|---|---|
+| Authorizations | `Authorizations_*authorizations.csv` | one auth attempt | `Timestamp` |
+| Settlements | `Sales-and-refunds_*settlements.csv` | one sale or refund | `Timestamp` or `Settlement date` |
+| Chargebacks | `Chargebacks_*chargebacks.csv` | one dispute | `Chargeback date`; origination via `Original transaction timestamp` |
+
+A run may use one, two, or all three layers. Name every layer used and every layer
+missing.
+
+## Portfolio constants to record
+
+When columns exist and are near-constant, state them once (do not treat as
+drivers):
+
+- MID / Gateway MID
+- MCC
+- Provider / acquirer path
+- Transaction source / entry method
+- Billing descriptor / sub merchant
+
+## Keys and joins
+
+| Join | Left | Right | Notes |
+|---|---|---|---|
+| Auth ↔ Chargeback | `Order ID` | `Original transaction order ID` | Primary for this Pazien-style extract |
+| Auth ↔ Settlement | `Order ID` | `Order ID` | May be 1:n if capture/refund splits |
+| Weak identity | masked `Account`, `IIN` | same | Collisions possible; fine for contribution tables, not unique-customer claims |
+
+Report match rates whenever a join supports a claim (“N of M chargebacks match an
+auth in file”).
+
+## Currency
+
+Reporting amounts are USD. Conversion rules: [fx.md](fx.md).
+
+1. Prefer native USD rows; convert every non-USD amount before summing.
+2. Never add USD + EUR (etc.) into one total without FX and a disclosure.
+3. Count KPIs never need FX.
+
+## Window selection
+
+| User ask | Default |
+|---|---|
+| Full extract | min→max of chosen time field |
+| Most recent week / last 7 days | `(max_ts - 7d, max_ts]` |
+| Calendar week | dates in that Mon–Sun (or local week rule; state it) |
+| Compare recent vs prior | split at the same cut; show both |
+
+Chargeback **programme 拒付率** uses received month (`Chargeback date`) per
+[chargebacks.md](chargebacks.md). If you also show origination-month incidence,
+label that separately so it is not mistaken for the Visa/Mastercard rate.
+
+## Decline taxonomy (auth)
+
+Map with both code and message when present (example Pazien-style):
+
+| Code | Message (typical) | Class |
+|---|---|---|
+| A001 | Approval - generic | approval |
+| D102 | Suspected fraud | hard / fraud-coded |
+| D104 | Insufficient funds | soft / funds |
+| D387 | Policy reasons | hard / policy |
+| D202 | Security code invalid | hard / data |
+| D204 | Invalid Expiration date | hard / data |
+| D210 | Do not honor | soft / issuer |
+| R014 | Invalid transaction | reject |
+
+Always recompute from the file; do not assume codes are portable across gateways.
+
+## What not to infer
+
+- BIN country ≠ shipping or billing country
+- Approval ≠ settled funds
+- Suspected-fraud decline ≠ confirmed fraud loss
+- Chargeback reason Fraud ≠ first-party vs third-party adjudication

package/skills/payment/payment-analysis/references/fx.md

@@ -0,0 +1,59 @@
+# Amount currency → USD (Forex Service)
+
+Reporting amounts are **USD**. Count KPIs never need FX.
+
+Use the Forex Service (`~/projects/forex`), not a provider SDK, not a
+spreadsheet rate, not realtime quotes for historical windows.
+
+## Which amount
+
+| Layer | Amount | Currency |
+|---|---|---|
+| Authorization | `Transaction amount` | `Transaction amount currency` |
+| Settlement | `Settlement amount` (fallback `Transaction amount`) | `Settlement amount currency` |
+| Chargeback | `Dispute amount` | `Dispute amount currency` |
+
+Ignore empty `Pre-DCC amount` (often `0` with blank currency). Do not treat BIN
+country as the transaction currency.
+
+## Rules
+
+1. If every used currency field is `USD`, keep native amounts. Write
+   `金额均为 USD`. Do **not** call Forex Service and do **not** write
+   `未做汇率折算`.
+2. If any row is not USD, convert **that row** to USD before any amount sum,
+   share, ticket size, or dual-axis amount chart.
+3. Historical / windowed reports use **daily** conversion, not realtime:
+
+   `POST {FOREX_BASE_URL}/api/v1/conversions/daily`
+
+   Body:
+
+   ```json
+   {
+     "quoteCurrency": "USD",
+     "date": "<UTC Rate Date = transaction date in the extract>",
+     "items": [{ "currency": "EUR", "amount": "100.00" }]
+   }
+   ```
+
+   Prefer one request per Rate Date: either `conversions/daily` for the day's
+   distinct currencies, or `POST /api/v1/rates/daily` then multiply locally
+   (`converted = native × rate`, decimal strings).
+4. Fail closed if a non-USD row has no daily rate. Do not drop it silently and
+   do not mix native EUR with USD in one total.
+5. Auth: `forex:read` bearer token, audience `forex-service`. Base URL default
+   `https://forex.1above.io`. Contract: `GET /integration/agent.json`.
+6. Footnote converted reports: Rate Date rule, quote USD, Forex Service daily
+   conversion (not realtime). Mark `realtimeFallback` if a current UTC day was
+   served as provisional.
+
+## Env
+
+| Variable | Role |
+|---|---|
+| `FOREX_BASE_URL` | Default `https://forex.1above.io` |
+| `FOREX_TOKEN` | Bearer with scope `forex:read` |
+
+Mint the token from Identity (`client_credentials`, audience `forex-service`,
+scope `forex:read`) as in the Forex Service integration guide.

package/skills/payment/payment-analysis/references/journey.md

@@ -0,0 +1,78 @@
+# Payment journey (Sankey)
+
+The journey is a **count** Sankey across checkpoints. Prefer ECharts (or
+equivalent). Do not mix count and amount on one Sankey.
+
+## Checkpoint order
+
+```text
+start → risk decision → 3DS → authorization → settlement
+```
+
+## Canonical state transitions
+
+Use these edge names when the underlying fields exist:
+
+| From | To |
+|---|---|
+| risk decision | accept |
+| risk review | 3DS init |
+| accept | non-3DS authorization |
+| non-3DS authorization | non-3DS authorization approved |
+| non-3DS authorization | non-3DS authorization declined |
+| 3DS init | 3DS challenge |
+| 3DS init | 3DS frictionless |
+| 3DS init | 3DS reject |
+| 3DS challenge | 3DS authenticated |
+| 3DS challenge | 3DS authentication failed |
+| 3DS authenticated | 3DS authorization |
+| 3DS authorization | 3DS authorization approved |
+| 3DS authorization | 3DS authorization declined |
+
+Settlement edges (when settlement layer present), from approved authorization
+nodes only:
+
+| From | To |
+|---|---|
+| non-3DS / 3DS authorization approved | settled sale |
+| non-3DS / 3DS authorization approved | approved not settled |
+| settled sale | refund (only if Order ID joins cleanly) |
+| settled sale | chargeback fraud / non-fraud (optional) |
+
+## Skip unavailable checkpoints
+
+If a checkpoint has no usable field in the extract, **omit its nodes and edges**.
+Do not invent risk decisions or 3DS outcomes.
+
+Examples:
+
+- `Authentication method` / 3DS result all null → skip risk decision, risk
+  review, and every 3DS node. Collapse to:
+
+  ```text
+  start → authorization → authorization approved / declined → settlement…
+  ```
+
+- Settlement file absent → stop after authorization approved/declined.
+- Refunds with Order IDs that do not join auth approvals → footnote only; do not
+  force a refund edge.
+
+Caption must list skipped checkpoints.
+
+## Mapping hints (when fields exist)
+
+| Journey node | Typical source |
+|---|---|
+| risk decision / risk review | gateway risk action, review queue, step-up flag |
+| accept | risk allow / no step-up |
+| 3DS init / challenge / frictionless / reject | 3DS status / ECI / transStatus |
+| 3DS authenticated / failed | challenge result |
+| non-3DS / 3DS authorization approved | auth response = approval |
+| non-3DS / 3DS authorization declined | auth response ≠ approval |
+| settled sale | settlement type = Sale joined on Order ID |
+
+## Anti-patterns
+
+- Drawing 3DS branches when authentication fields are empty
+- Using amount on the journey Sankey
+- Putting decline-reason fan-out on the journey (keep that in Topics charts)