@1aboveio/skills 1.0.22 → 1.0.24

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -369,7 +369,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "522a4876e0519a4163ff85976caa478a024aaacb3115f1e0cb1b4ac2832c90df",
+      "contentDigest": "29683c062ba8b578e045766c7cb7f289f8a71297935bf010b4eb460340563607",
       "digestExcludes": []
     },
     {
@@ -382,7 +382,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "e1d2a60487eec9d1fd4fec1a4f0357069904db25577c08b811a72106da86c140",
+      "contentDigest": "e3d3eaef2db3103142a762562ea6d7e677b18b7e3c38b1ec4236cbc4d09cac18",
       "digestExcludes": []
     },
     {
@@ -395,7 +395,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "81c172a2db0fe9750447af937247b8e6aed9c47928db1c0e003bba7e5c64bbc3",
+      "contentDigest": "5dd7c2517cf5eb057185f85529c45ff5c224ef80da402ab0f3b08c813da5a7d1",
       "digestExcludes": []
     },
     {
@@ -408,7 +408,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "351eaa56339849c1994c0d5735a287d5bb1aabc02225b93336b1bbc547696390",
+      "contentDigest": "aeda57d34ef5ef67685c1da51ec8e51222944ecd31c2c88655f3dac3a6883477",
       "digestExcludes": []
     },
     {
@@ -421,7 +421,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "6a1a1689ae2616d2f6f4afe4442ec72f0a54e8d829ddbf38546ed0d881a14da1",
+      "contentDigest": "045d39cf7e09f6c6b0873f2ed0864099c53d7c19fff6010e7934d3f506b9dbfa",
       "digestExcludes": []
     },
     {
@@ -434,7 +434,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "b740e99373209a7691f412d5bf7e685d82f5a50a1943ef2fd75f0395048aec4a",
+      "contentDigest": "c0e6a5e98ca8ba16f74db327f8e1a904b203b2cc27c7117cab2915053eb79b02",
       "digestExcludes": []
     },
     {
@@ -447,7 +447,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "d6589a126bc271d6b7953fc68c316c3f5b229c34215c3624074c0ffe657ef718",
+      "contentDigest": "a328bebf87a4c4ef2ebd2fd583121a716c1604ba030e8646faaa8d57ea39acb4",
       "digestExcludes": []
     },
     {
@@ -460,7 +460,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "e38611409ef33c5b33ae489c43c476f85e176003db7d24b031891e52c2875d8e",
+      "contentDigest": "b53f8bace45c4e33a64d2a312935353b0aad3b796b62ec88837253ae7a59373c",
       "digestExcludes": []
     },
     {
@@ -473,7 +473,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "7f78a80abbadcc3bfdf9d70f477b26370758d4ad3a3f860c1b73db5d3166c10a",
+      "contentDigest": "996ca889528de252b26ccd7d3abff3be4e84c5d3764a36b987a557e77f3c8dc2",
       "digestExcludes": []
     },
     {
@@ -486,7 +486,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ae28f9f440c015a3ac9935cd050f8d489d6355172cb3cff5df72ab50e1c7dc89",
+      "contentDigest": "01139259ede94fa4eeca72b5f24e09cdea6f142f629d602aa834ec1d47ad52cd",
       "digestExcludes": []
     },
     {
@@ -499,7 +499,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ffc64d184a564bcc131edb40d2b71ecfb63ba96a53cb25d810235e09ad0222b4",
+      "contentDigest": "9900e06e2edaaa3b22244f4e3d2b35ee7fcd22e8cf1d851b4624777f8e3f48c3",
       "digestExcludes": []
     },
     {
@@ -512,13 +512,13 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "3f11192933319bed874a91b004a2f41629a74b3d5f44e0c27d6a8ba2b31ce2dd",
+      "contentDigest": "1fe2db94e6ddd37e2e3d31aece765171cb71e196f7efed0db34ea14b50a6c397",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "40e572635a1e002b4ab249a50b88a1e07cc59a64d8fcb39b5efa91c3bd6091ff",
+  "releaseIdentity": "79ed0ccd1faeea594111478cfd1efd095b941ad2680904ff48d9e5859a5f64d9",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",

package/skills/engineering/ensure-coverage/SKILL.md

@@ -2,7 +2,7 @@
 name: ensure-coverage
 description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
 disable-model-invocation: true
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Ensure Coverage

package/skills/engineering/golden-path/SKILL.md

@@ -3,7 +3,7 @@ name: golden-path
 description: "Golden-path E2E: the short list of user journeys whose failure blocks a release, kept in a repo as one contract (golden-paths.json) with a generated GOLDEN_PATHS.md and a generated GitHub Actions workflow, and run against a local build or a deployed URL for an ALIVE/DEAD verdict. Use to set golden paths up in a repo ('init golden paths', 'add golden-path CI'), to migrate an older smoke.manifest.json or a hand-built smoke setup ('audit', 'migrate smoke'), to add, change, or remove a golden path, to ask 'is the build alive?' or run them before a PR or release, or when a change touches a flow listed in GOLDEN_PATHS.md. NOT for writing the Playwright specs themselves (e2e-test), deciding what a change must prove (ensure-coverage), or general workflow YAML (github-actions)."
 dependencies:
   - e2e-test
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Golden path

package/skills/engineering/harness-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: harness-runtime
 description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Harness Runtime

package/skills/engineering/resolve-issues/SKILL.md

@@ -8,7 +8,7 @@ dependencies:
   - better-review
   - golden-path
   - harness-runtime
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve issues

package/skills/engineering/resolve-release/SKILL.md

@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
 disable-model-invocation: true
 metadata:
   workflow-role: coordinator
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve release

package/skills/engineering/rush-issues/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-issues
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush issues (shortcut of resolve-issues)

package/skills/engineering/rush-release/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-release
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush release (shortcut of resolve-release)

package/skills/engineering/test-quality/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: test-quality
 description: "Seven principles for tests that catch real bugs, and an audit that reports weak, redundant, and not-coverage tests without fixing them. Use when writing, changing, or reviewing tests, or when asked whether tests are useful, redundant, over-mocked, flaky, only assert static text, or test config files, or asked to make a slow test suite faster without losing coverage, or when the user asks to write the testing conventions into a repo's CONTRIBUTING.md. NOT defining what a spec must prove (ensure-coverage) or authoring browser tests (e2e-test)."
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Test Quality

package/skills/risk-compliance/compliance-audit/SKILL.md

@@ -2,7 +2,7 @@
 name: compliance-audit
 version: 2.9.0
 description: "Audit operations against financial-compliance checklists (AML/KYC, VARS, PCI-DSS, TPA oversight, onboarding, transaction monitoring). Produces tracker.md (with a tracker.xlsx export) and phase-trail.md with layered validation; cites evidence by original filename. Input: reg-parser or the built-in VARS checklist."
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Compliance Audit

package/skills/risk-compliance/contract-compare/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: contract-compare
 description: "Compare two or more contracts side-by-side for structured diff, gap analysis, and benchmarking. Use when: comparing contracts or agreements, contract diff, compare terms, vendor-vs-vendor, compare our template vs theirs, compliance gap between contracts. NOT for single-contract risk review — use contract-review for that."
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Contract Compare

package/skills/risk-compliance/contract-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: contract-review
 description: "Review contracts for legal, commercial, and compliance risks via convert → chunk review → merge → validate (+ optional mandate preprocessing). Use for reviewing, auditing, or checking any contract, agreement, NDA, MSA, or SLA; input a file path (PDF/DOCX/TXT) or pasted text."
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Contract Review

package/skills/risk-compliance/doc-authenticity/SKILL.md

@@ -3,7 +3,7 @@ name: doc-authenticity
 version: 0.4.1
 description: "Screen PDF documents and raster images for fabrication, tampering, Photoshop or other image-editor use, and content validity. Detects file type, runs format-specific authenticity forensics, classifies bank statements, conversation logs, invoices, agreements, and other documents, then applies type-specific validity checks. Produces separate authenticity (NO_EVIDENCE_OF_MODIFICATION / SUSPICIOUS / LIKELY_MODIFIED / INCONCLUSIVE) and validity (VALID / INVALID / INCONCLUSIVE) verdicts. Use whenever a user asks whether a document, screenshot, scan, statement, invoice, contract, chat log, receipt, or payment evidence is genuine, original, edited, Photoshopped, manipulated, fake, or valid."
 disable-model-invocation: true
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Document and Image Authenticity

package/skills/risk-compliance/fraud-detection/SKILL.md

@@ -12,7 +12,7 @@ description: >
   impact, and a business report. Use for fraud, scam, mule, account-takeover,
   chargeback, dispute, transfer, collection, or payout risk analysis even when the
   user does not name this skill.
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Fraud Detection

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

@@ -14,7 +14,7 @@ description: >
   transactions" — even if they do not say payment-analysis. Do NOT use for
   fraud rule discovery (fraud-detection) or TLD / MCC-miscoding
   clusters (tld-detection).
-release-version: 0.50.2
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Payment Analysis

package/skills/risk-compliance/portfolio-payment-analysis/SKILL.md

@@ -1,170 +1,90 @@
 ---
 name: portfolio-payment-analysis
-description: >
-  Analyze submerchants in Helipay/Worldpay aggregator exports: compare merchants
-  and investigate selected merchants' authorization, settlement and disputes,
-  including descriptor mapping and overlapping exports. Portfolio-level payment
-  overviews belong to payment-analysis; fraud rule discovery belongs to fraud-detection.
-release-version: 0.50.2
+description: Analyze Helipay/Worldpay submerchants from authorization, settlement, dispute and DART-340 exports; compare merchants and produce an offline interactive Chinese merchant report. Use for aggregator merchant comparisons, merchant authorization performance, issuer drilldown, merchant fraud/dispute histories and VAMP extract estimates. Portfolio-wide overviews belong to payment-analysis; fraud rule discovery belongs to fraud-detection.
+release-version: 0.50.4
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Portfolio payment analysis
 
-Before report drafting or substantive review, read
-`{house-style baseDir}/references/analytical-reporting.md` and its
-required writing-pattern and definition references. Use `write-report` for the report stage
-with this skill's merchant template, not `write-doc` or the portfolio report layout. Give
-delegated writers and reviewers the same resolved reference paths and require the reads;
-keep merchant metrics, confidentiality and specialist checks unchanged. Individual native
-selections also need `write-report` and its required `terminology` dependency; installation
-metadata does not load instructions. Missing required resources leave the report stage incomplete.
+Analyze attributed payment portfolios and produce an internal Chinese merchant report
+by default. Worldpay CSV and DART-340 are the bundled adapters; other sources need
+verified field and identity mappings. Keep private extracts local and synthetic
+fixtures in the repository.
 
-Produce an internal submerchant report in Chinese by default, with merchant comparisons
-and detail for merchants the user selects. Treat the extracts as confidential; do not
-publish them or include cardholder data in the report. Use the installed
-`payment-analysis` skill as the base: read its `SKILL.md` and relevant references for
-periods, event layers, metrics, daily USD FX, disputes, visualization and editorial
-checks. This skill owns the aggregator report structure in
-[metrics and reporting](references/metrics-and-reporting.md); that template replaces
-the base report's chapter order and mandatory Sankey. Inherit the base's metric,
-FX, dispute, terminology and fact-preservation rules. Pass the aggregator template
-to editorial review. Scope any payment-stage evidence to a merchant; do not include a
-portfolio funnel or Sankey.
-
-For a clean individual native installation, select `portfolio-payment-analysis`,
-`payment-analysis`, `write-report`, `editorial-review`, `polish-cn`, `terminology`, and `house-style`; the native
-picker does not install dependencies automatically. The generated Payment install
-group recipe includes the dependency closure.
+Start with [workflow and module contracts](references/workflow-and-contracts.md), then
+apply the [report structure](references/metrics-and-reporting.md). Follow the stages
+below in order; scripts implement these contracts rather than define business scope.
 
 ## Workflow
 
-1. Inventory authorized Helipay/Worldpay inputs, source coverage, event dates,
-   timezone, currencies, identifiers, field dictionaries and reporting periods.
-   Record missing and partial layers. Use the requested period and merchant selection;
-   otherwise apply the base skill's period-selection rule, then pass both required
-   CLI dates explicitly. Identify an unsupported or unresolved period
-   rather than inventing one.
-2. Read [identity and reconciliation](references/identity-and-reconciliation.md)
-   before deduplication or joining. Build the mapping and reconciliation evidence;
-   scope every join to the same verified merchant and source namespace. Unknown or
-   conflicting identities are not reassigned by descriptor or order similarity.
-3. Read [metrics and reporting](references/metrics-and-reporting.md). Compute
-   merchant rates with merchant-specific denominators and disclose sample counts.
-   Include week-by-week comparisons for every submerchant within the report period,
-   using Monday–Sunday weeks and explicit partial-week labels. Compare other periods
-   for individual merchants when explicitly requested and supported.
-   Read [risk history](references/risk-history.md) for 340FRD, dispute histories
-   and VAMP. Use the base skill's FX and dispute rules; leave unsupported figures
-   unresolved, not zero.
-4. Present merchant findings, comparison, selected merchant detail and merchant-specific
-   investigation actions. Explain missing data, conflicts, unmatched records, rate
-   denominators and attribution limits. Keep totals only as internal reconciliation
-   evidence; do not report portfolio summaries, trends, decomposition, funnels or
-   overall dispute chapters.
-   Follow the base skill's editorial review, Chinese polish and fact-preservation
-   checks when producing a complete report.
-
-## CLI and scope
-
-The bundled workflow uses Python 3 standard-library scripts and local Worldpay CSV
-exports. It makes no network calls. Authorization data is required; settlement and
-dispute files are used when supplied. Run all three commands:
+1. Read the installed `payment-analysis/SKILL.md` and its event-layer, metric, FX,
+   dispute and terminology references. Inventory authorized inputs, source dictionaries,
+   merchant/provider identifiers, coverage, timezone and currencies. Fix explicit main
+   dates using the user's period or the base period-selection question. The common cutoff
+   is the earliest supplied layer's last event date for the main table and risk history.
+   Authorization charts use the earlier of requested end and last authorization date,
+   independently of settlement coverage; disclose both cutoffs and partial periods.
+2. Before deduplication or joins, read [identity and reconciliation](references/identity-and-reconciliation.md).
+   Scope identity and joins to the verified merchant/provider namespace. Descriptor,
+   Gateway MID and MID are not interchangeable submerchant keys. Conflicting auth or
+   settlement identities stop generation; retain unresolved attribution explicitly.
+3. Read [metrics and reporting](references/metrics-and-reporting.md) and
+   [risk history](references/risk-history.md). Use the bundled calculator and builder
+   for merchant-specific denominators, two-period detail, current-week issuer top five,
+   eight-week amount/count trends and risk count/rate histories. Unknown amounts or
+   missing daily USD FX leave affected sums unavailable, not mixed-currency totals.
+4. Use `write-report` for the report stage with this skill's template. Read
+   `house-style/references/analytical-reporting.md`, `analytical-writing-patterns.md`
+   and `definitions-and-metrics.md`; load required `terminology`, `editorial-review`
+   and domain-required `polish-cn`. Pass the same references and merchant template to
+   any authorized writer/reviewer. Missing dependencies leave report review incomplete.
+   Review `presentation.json`, apply narrative edits there and rerender both outputs.
+5. Verify arithmetic, chart values, current-week issuer selection, null/zero semantics,
+   tabs, tooltips, drilldown and offline printing. Open the saved HTML in a local browser;
+   rendering instructions alone are not visual verification. Retain check evidence outside
+   the business report and state any unverified rendering or missing data.
+
+## Local CLI
+
+The calculator uses Python standard-library CSV exports. ECharts is pinned and bundled;
+report generation and viewing make no network calls.
 
 ```sh
-python3 {portfolio-payment-analysis baseDir}/scripts/analyze.py --input PATH --output OUTPUT --main-start YYYY-MM-DD --main-end YYYY-MM-DD
-python3 {portfolio-payment-analysis baseDir}/scripts/build_report.py --facts OUTPUT/facts.json --output OUTPUT
-# After editing or polishing presentation.json, rerender without rebuilding its narrative:
-python3 {portfolio-payment-analysis baseDir}/scripts/render.py --model OUTPUT/presentation.json --output OUTPUT
+python3 {skill-dir}/scripts/analyze.py --input PATH --output OUTPUT --main-start YYYY-MM-DD --main-end YYYY-MM-DD
+python3 {skill-dir}/scripts/build_report.py --facts OUTPUT/facts.json --output OUTPUT
+python3 {skill-dir}/scripts/render.py --model OUTPUT/presentation.json --output OUTPUT
 ```
 
-The calculator caps the requested end at the earliest last event date among supplied
-layers. It reports the effective cutoff and compares the corresponding prior-month
-dates. Source event ranges alone do not establish continuous coverage. Check period lengths
-and source coverage before interpreting a comparison.
-
-The report outputs are `overview.zh.html` and `overview.zh.md`, backed by the reviewed
-`presentation.json`. Supporting internal files are `facts.json`, `merchant-metrics.csv`,
-`merchant-mapping.csv`, `merchant-weekly.csv`, `merchant-segments.csv`,
-`merchant-detail-comparison.csv`, `merchant-risk-history.csv`, and
-`coverage-and-reconciliation.json`; legacy aggregate fields
-in these files are not report deliverables. The HTML is self-contained, supports
-merchant filtering and printing, and sends no data to external services. Use
-`--detail-merchant ID` on `build_report.py` (repeat it for several IDs) when the user
-names merchants. Otherwise expand the largest merchant by attempts and the lowest-rate
-merchant with at least 30 attempts, while keeping every other merchant available in
-collapsed detail sections. This is a navigation rule, not a significance test.
-Section 2 retains full weekly history. Section 3 uses charts to compare only this week
-with last week, matching weekdays when the current week is partial. Every merchant
-has BIN-country, card-product (payment method × card type), fixed USD amount-bucket,
-authentication and unsuccessful-response charts. Country and card-product charts use
-compact paired bars. Amount buckets use side-by-side histograms, unsuccessful responses
-use side-by-side bars, and authentication uses paired pies for counts and USD amounts,
-not rates. Each pair compares aligned weeks. Use the shared `comparison_charts.py` for
-all report charts. Section 3 omits settlement sales/refunds. Include merchant risk
-history charts as specified in the risk reference. Treat 340FRD file generation date
-as its report date, retaining the earliest date for exact repeats. Monthly dispute
-and fraud charts offer counts and network-style rate estimates with numerator and
-denominator details; weekly charts retain counts. Visa uses same-month sales,
-Mastercard ECP uses prior-month sales, and EFM uses fraud chargebacks divided by
-prior-month e-commerce sales, not all 340FRD Mastercard reports. Fix groups across the union of the
-two comparison periods, and display
-only those two ranges in chart legends and expandable metric-row tables. Follow the
-segment and denominator contract in the reporting reference.
-Include merchant-specific historical refund and dispute follow-ups in the action table
-when supported, without adding portfolio history chapters. If the user says a merchant is
-historical and out of this report, pass `--exclude-merchant ID` (repeat it for several IDs).
-That removes the merchant from comparison, weekly tables, detail, the action list, and every
-linked merchant CSV. State the exclusion once: it is not a closure finding and not missing data.
-Do not lead the report with an excluded merchant. A later rebuild without the flag puts the
-merchant back.
-
-The generated lowest-authorization-rate sentence only chooses an authorization review. It is
-not the investigation order. If fraud or predispute history would change who a reader checks
-first, put that merchant and month in the opening, and say whether the month is inside the
-report window. Do not title a real extract 样本报告; 样本 is only for a small attempt count.
-
-A packed week cell that includes dollars must say 授权成功 USD. The rule against repeating a
-metric label applies only when the column header already names that measure. When the sales
-column contains both 0.00 and blank, say which merchants have an observed zero and which have
-no settlement layer. An invalid or post-cutoff 340FRD file must state the effect on counts, not
-only the date. Unmatched fraud records must state the count and amount excluded from merchant
-figures.
-
-The report includes per-submerchant weekly counts, rates, successful authorization
-amount USD, settled sales, refunds and dispute observations. Each merchant's breakdown
-uses date/week columns and metric rows; successful authorization amount has its own
-row and never substitutes settled sales. Only adjacent full calendar weeks with available observations and valid
-denominators receive week-over-week changes; partial weeks retain their metrics but
-have no week-over-week change. Read the weekly contract in the reporting reference.
-
-The optional `--fx-rates` accepts caller-supplied daily USD rates. The CLI does not
-verify their provenance; obtain and preserve Forex Service evidence as specified by
-the base FX contract before relying on converted amounts. Without a required rate,
-the affected amount is unavailable while count metrics remain available. Render unavailable
-cells blank, not N/A; show only `USD 33...` in a USD value cell, without repeating its
-metric label. Remove extra explanatory prose while retaining necessary coverage limits.
-
-Source fields remain unchanged in JSON. CSV exports prefix spreadsheet-sensitive
-text with an apostrophe so opening a report does not execute merchant names or
-labels as formulas; numeric metrics remain numeric.
-
-Treat internal authorization counters together with `layer_observed.auth`: a zero
-observation count with that flag false is not confirmed zero business activity.
-The report and business CSV cells remain blank in that case. Distinguish observed
-dispute snapshots from deduplicated case-stage counts and verified opening counts;
-they answer different questions and need not match. Formatting-only aliases of a
-verified provider are duplicates, not new snapshots. Sales or refunds without
-stable event identity remain observations, not confirmed monetary totals.
-
-The report is an extract-based operational view. The v1 CLI refuses generation if
-any authorization or settlement identity has conflicting values; resolve those
-sources before rerunning. This conservative refusal can block clean periods too.
-It never substitutes totals from an unlabeled clean subset. An absent layer or a
-window without observed settlement/dispute rows produces unavailable metrics, not
-confirmed zero activity. Dispute rows remain observed
-snapshots until opening semantics are verified. The CLI computes supported
-network-style extract estimates, not official network assessments; unsupported rate
-cells stay blank. Merchant-scoped settlement and join evidence must not imply that all
-current-period sales descend from current-period approvals. Review the saved
-`presentation.json` as the narrative source, then rerender both formats. Preserve
-raw customer data in the input project; use synthetic fixtures for repository tests.
+Outputs: `overview.zh.html`, `overview.zh.md`, reviewed `presentation.json`, `facts.json`
+and merchant CSV/JSON reconciliation evidence. HTML embeds ECharts, all aggregate data
+and third-party notices; it works offline without React or a CDN. Calculations stay in
+facts, presentation owns narrative, rendering does not recompute payments.
+
+`--detail-merchant ID` selects the initial merchant tab; all merchants remain accessible.
+`--exclude-merchant ID` removes an explicitly excluded historical merchant from report and
+business exports; repeat either flag as needed. State an exclusion once, not as a closure
+finding. `--fx-rates` accepts daily USD rates only with preserved Forex Service provenance;
+the CLI cannot certify caller-supplied provenance.
+
+For selected Parquet snapshots, retain their source-selection accounting. Recover missing
+source fields only through verified file hashes and source row references, with row-count
+reconciliation. Do not rerun raw overlapping exports as a second payment population or
+infer merchant identity from descriptors. The CSV CLI does not directly read Parquet.
+
+## Presentation contract
+
+Use only `1. 子商户对比` and `3. 重点子商户详情`, with merchant findings above them.
+The first table includes daily authorization-attempt count sparklines and actual approved
+authorization USD amounts, not sales. Every merchant gets a tab; the tab starts with up
+to eight observed calendar weeks of amount bars and count lines. Country and card-product
+charts show approval rate plus approvals/attempts only. Country drilldown selects its
+Top 5 banks using positive **current-period** attempts, keeps prior-period values for
+those same banks and retains undefined rates as gaps. Other comparison dimensions keep
+the paired-chart layouts in the reporting reference.
+
+All five risk histories show count bars and rate lines simultaneously. VAMP is an explicitly
+labeled extract estimate from Visa TC40 plus already-opened formal disputes over same-month
+merchant Visa sales; pending/response/loss/reversal status does not remove a formal case.
+Official network assessment remains distinct. No portfolio funnel, totals chapter, weekly
+summary chapter, action chapter, coverage chapter, chart detail expansion or VAMP component
+table is rendered; supporting evidence remains available in files.