@morroc/open-ledger 0.14.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Phureewat Aphibansri
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,191 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img src="assets/logo.svg" alt="OpenLedger" width="108">
+  </picture>
+</p>
+
+<h1 align="center">OpenLedger</h1>
+
+<p align="center">
+  <strong>The Harness Layer for Personal Finance</strong>
+</p>
+
+<p align="center">
+    A harness that turns scattered financial statements into a private, deterministic ledger for your AI.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@morroc/open-ledger"><img src="https://img.shields.io/npm/v/@morroc/open-ledger.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@morroc/open-ledger"><img src="https://img.shields.io/npm/dt/@morroc/open-ledger.svg" alt="npm total downloads" /></a>
+</p>
+
+<br />
+
+You've tried many personal finance apps from the App Store. None of them fits what you need, because each is someone else's idea of your money and lifestyle. So you asked AI to build the one that would, and it failed you too. It hallucinated the numbers, mangled your data, and never quite understood what you wanted.
+
+AI fails when it has nowhere reliable to keep the numbers. OpenLedger gives it that place, a deterministic harness that holds every number in your own records.
+
+OpenLedger is a secure bookkeeping that serves as a harness for your AI. The data source is what you already receive which are monthly statements from your banks and credit cards. Your AI reads each statement and records what it finds as double-entry bookkeeping.
+
+Everything stays on your machine, the database is fully encrypted, and what the harness returns to your AI has PII redacted by default before it sends to AI provider. No bank logins, no bank API keys, no cloud aggregator needed, just the bank documents you already have as the source of truth.
+
+By using this harness, your AI can build the app you never found: a budget tracker that fits your lifestyle, a subscription auditor, a retirement planner, a personal money coach. Your finance app is yours to reimagine, and everything you build reads from the same ledger, so you can keep adding without starting over.
+
+## Use OpenLedger with your AI
+
+The whole skill is one file: [`skills/SKILL.md`](./skills/SKILL.md). Every host gets the same bytes; `oled setup --print` prints them.
+
+### AI Chat Apps (ChatGPT, Claude, Gemini, Kimi)
+
+1. Install [Node.js](https://nodejs.org) (LTS), then paste into your terminal:
+
+   ```bash
+   npm install -g @morroc/open-ledger
+   ```
+
+2. Paste into your AI chat:
+
+   ```
+   Fetch https://raw.githubusercontent.com/phureewat29/open-ledger/main/skills/SKILL.md
+   and follow it. oled is installed; help me set up my ledger.
+   ```
+
+   If your chat app cannot fetch URLs, paste the skill itself: `oled setup --print | pbcopy` copies it; drop it into the first message or the app's custom instructions.
+
+Your AI walks you through the rest.
+
+### Coding Agents (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, PI)
+
+```bash
+npm install -g @morroc/open-ledger
+npx skills add phureewat29/open-ledger
+```
+
+Or run `oled setup`, which writes the skill to `.agents/skills/`, the shared directory most agents read (use `--host claude` for Claude Code).
+
+### Your own agent stack
+
+Every command speaks `--json` with typed exit codes, built to be scripted. `oled setup --dir <agent-home>` installs the skill anywhere. Two complete references ship in this repo: [`examples/corgi-claude`](./examples/corgi-claude) runs the statement-to-answers loop with `claude -p`, and [`examples/corgi-eval`](./examples/corgi-eval) runs evals against any model and scores how well the harness fits.
+
+With the skill installed, give your agent a real task:
+
+1. Start with the statements you have waiting: *"Ingest my new statements."* It discovers new files, prepares and reads each one, commits the transactions it finds, and raises a question for anything it can't resolve on its own.
+2. Clear whatever it flagged: *"Show me anything you weren't sure about, and let's resolve it."* It walks you through open questions, such as an unrecognized merchant or an ambiguous account match, one at a time.
+3. With the ledger current, ask for the payoff: *"What's my net worth, and where did most of my spending go last month?"* It reads the answer straight from the ledger.
+
+## The Agent Workflow
+
+Every row becomes a *transaction*: it debits one account and credits another by the same positive amount.
+
+This is the loop the skill teaches an agent to run:
+
+1. **Discover**: `oled ingest list --json` to find new/pending files.
+2. **Prepare**: `oled ingest prepare <path>` registers the file and extracts it, unlocking encrypted PDFs via `oled vault`. A PDF carrying its own text layer, or a scan read by a configured OCR endpoint, comes back as a `document` text file. With no text layer and no OCR endpoint, it comes back as one image per page.
+3. **Read**: the agent reads what prepare returned, either the text document or the page images, and picks out every transaction row.
+4. **Commit**: the agent pipes the transactions it extracted (one debit account, one credit account, one positive amount per row; splits go as a compound `linked` group) into `oled ingest commit`. The harness posts them into the ledger and raises a question for anything it can't resolve confidently (unknown merchant, fuzzy account match, uncategorized fallback, cross-currency row).
+5. **Resolve**: the agent (or you) works through `oled questions` for whatever got raised, then closes the file out with `oled ingest done <id>`.
+
+## Commands
+
+Run `oled --help` (or `oled <noun> --help`) for the full flag reference. Grouped overview:
+
+```
+oled                # Status: config, database, ledger counts, net worth (default)
+oled doctor         # Diagnose the harness environment
+oled setup          # Install the skill for an agent CLI (--host <id> | --dir <path>)
+oled config         # Configuration
+
+oled ingest         # Ingest pipeline: list / prepare / commit / done / fail
+oled files          # Browse ingested files (list / show / drop)
+oled vault          # Manage file-password patterns for encrypted statements
+
+oled transactions   # Transactions: list / show / add / update / delete / recategorize / dedupe / merge
+oled accounts       # Manage the chart of accounts
+oled merchants      # Manage merchants and their default accounts
+oled questions      # List, answer, and defer open questions
+
+oled report         # Income, expenses, and net
+oled notes          # Manage freeform notes
+oled datasets       # Reference datasets
+
+oled open           # Open the data folder in file explorer
+```
+
+## Security & Privacy
+
+- All financial data stays on your machine, encrypted with AES-256 (libsql); default `~/.oled/db.sqlite`.
+- The config file (`~/.oled/config.json`) carries `0600` permissions. It holds two secrets at most, the database encryption key and the OCR endpoint API key; `config show` surfaces a fingerprint of each and `status` one of the database key, never the plaintext.
+- Encrypted-PDF passwords sit AES-GCM-encrypted in `db.sqlite` under a filename pattern; plaintext never touches disk.
+- A decrypted statement stays in memory. Only what an agent has to read is written to `cache/`: the extracted text, or the page images.
+- Read commands mask PII in free-text fields by default; `--no-redact` returns verbatim text.
+- No telemetry, no analytics. OpenLedger makes no network calls of its own. The exception is opt-in and goes only to the OCR endpoint you configure: `ingest prepare` sends it the page images to read, and `doctor` asks it which models it serves.
+
+## Configuration
+
+OpenLedger stores everything in `~/.oled/`:
+
+```
+~/.oled/
+  config.json    # locale, currency, paths, database encryption key (0600 permissions)
+  context.md     # persistent freeform context an agent can read (path shown as context_path in oled config show)
+  db.sqlite      # encrypted SQLite database
+  data/          # drop your statements here, as PDFs or images (subfolders allowed)
+  cache/         # extracted text and page images handed to an agent
+```
+
+### Environment variables
+
+See `.env.example` for the current list:
+
+```bash
+# OpenLedger environment variables. Copy this file to `.env` and fill the values.
+
+# Optional. Relocates the entire ~/.oled directory. Individual
+# OLED_* overrides below still win for their own paths.
+OLED_DIR=
+
+# Optional. Passphrase used to encrypt the local SQLite database (AES-256).
+# `oled config --generate-key` generates one if left blank.
+OLED_DB_ENCRYPTION_KEY=
+
+# Optional. Default: ~/.oled/db.sqlite
+OLED_DB_PATH=
+
+# Optional. Default: ~/.oled/data
+OLED_DATA_DIR=
+
+# Optional. Scratch space for the extracted text and page images handed to external
+# agent CLIs. Default: ~/.oled/cache
+OLED_CACHE_DIR=
+
+# Optional. OpenAI-compatible OCR endpoint base URL, including its version
+# segment, e.g. http://127.0.0.1:1234/v1. A non-local URL sends statement page
+# images off this machine.
+OLED_OCR_BASE_URL=
+
+# Optional. Model id served at OLED_OCR_BASE_URL. The id picks the built-in
+# prompt, sampling, and page-render profile; blank asks the endpoint for the
+# default profile's own model.
+OLED_OCR_MODEL=
+
+# Optional. API key for the OCR endpoint, if it requires one. Set it here or in
+# the shell: `oled config` has no flag for it.
+OLED_OCR_API_KEY=
+```
+
+## Contributing
+
+```bash
+git clone https://github.com/phureewat29/open-ledger
+cd open-ledger
+npm install
+npm run build
+npm link # makes 'oled' available globally
+```
+
+`npm run integration` builds the CLI and runs a two-stage integration test against the built binary: a read-surface sweep (NDJSON validity, exit codes, zero ANSI) and a full write-path lifecycle in an isolated environment.
+
+## License
+
+OpenLedger is licensed under the [Apache License 2.0](./LICENSE).

package/datasets/defaults/cn.json

@@ -0,0 +1 @@
+{ "country": "CN", "locale": "zh-CN", "currency": "CNY" }

package/datasets/defaults/jp.json

@@ -0,0 +1 @@
+{ "country": "JP", "locale": "ja-JP", "currency": "JPY" }

package/datasets/defaults/th.json

@@ -0,0 +1 @@
+{ "country": "TH", "locale": "th-TH", "currency": "THB" }

package/datasets/defaults/us.json

@@ -0,0 +1 @@
+{ "country": "US", "locale": "en-US", "currency": "USD" }

package/datasets/institutions/cn.json

@@ -0,0 +1,47 @@
+{
+  "country": "CN",
+  "institutions": [
+    { "code": "ICBC", "label": "Industrial and Commercial Bank of China (工商银行)", "kind": "bank", "notes": "Largest of the Big Four; state-owned." },
+    { "code": "CCB", "label": "China Construction Bank (建设银行)", "kind": "bank", "notes": "Big Four; state-owned." },
+    { "code": "ABC", "label": "Agricultural Bank of China (农业银行)", "kind": "bank", "notes": "Big Four; state-owned." },
+    { "code": "BOC", "label": "Bank of China (中国银行)", "kind": "bank", "notes": "Big Four; strongest overseas presence." },
+    { "code": "BOCOM", "label": "Bank of Communications (交通银行)", "kind": "bank", "notes": "Fifth large state bank." },
+    { "code": "PSBC", "label": "Postal Savings Bank of China (邮储银行)", "kind": "bank", "notes": "State-owned; rural reach." },
+    { "code": "CMB", "label": "China Merchants Bank (招商银行)", "kind": "bank", "notes": "Leading retail joint-stock bank." },
+    { "code": "CITIC-CN", "label": "China CITIC Bank (中信银行)", "kind": "bank" },
+    { "code": "SPDB", "label": "Shanghai Pudong Development Bank (浦发银行)", "kind": "bank" },
+    { "code": "CIB", "label": "Industrial Bank (兴业银行)", "kind": "bank" },
+    { "code": "CMBC", "label": "China Minsheng Bank (民生银行)", "kind": "bank", "notes": "Largest private bank." },
+    { "code": "PAB", "label": "Ping An Bank (平安银行)", "kind": "bank", "notes": "Ping An Group subsidiary." },
+    { "code": "CEB", "label": "China Everbright Bank (光大银行)", "kind": "bank" },
+    { "code": "HXB", "label": "Hua Xia Bank (华夏银行)", "kind": "bank" },
+    { "code": "CGB", "label": "China Guangfa Bank (广发银行)", "kind": "bank" },
+    { "code": "WEBANK", "label": "WeBank (微众银行)", "kind": "bank", "notes": "Digital-only; Tencent-backed." },
+    { "code": "MYBANK", "label": "MYbank (网商银行)", "kind": "bank", "notes": "Digital-only; Ant Group-backed." },
+    { "code": "ALIPAY", "label": "Alipay (支付宝)", "kind": "wallet", "notes": "Ant Group; dominant wallet alongside WeChat Pay." },
+    { "code": "WECHATPAY", "label": "WeChat Pay (微信支付)", "kind": "wallet", "notes": "Tencent." },
+    { "code": "JDPAY", "label": "JD Pay (京东支付)", "kind": "wallet", "notes": "JD.com." },
+    { "code": "UNIONPAY", "label": "UnionPay (银联)", "kind": "payment_rail", "notes": "National card network and QuickPass QR rail; appears on statements, not an account." },
+    { "code": "CITICSEC", "label": "CITIC Securities (中信证券)", "kind": "broker", "notes": "Largest broker." },
+    { "code": "HUATAI", "label": "Huatai Securities (华泰证券)", "kind": "broker" },
+    { "code": "GTJA", "label": "Guotai Junan Securities (国泰君安)", "kind": "broker", "notes": "Merged with Haitong (2025) as Guotai Haitong." },
+    { "code": "GFSEC", "label": "GF Securities (广发证券)", "kind": "broker" },
+    { "code": "GALAXY", "label": "China Galaxy Securities (银河证券)", "kind": "broker" },
+    { "code": "EASTMONEY", "label": "East Money Securities (东方财富)", "kind": "broker", "notes": "Leading online/retail broker." },
+    { "code": "FUTU", "label": "Futu (富途牛牛)", "kind": "broker", "notes": "HK-based app broker; serves mainland investors offshore." },
+    { "code": "TIGER", "label": "Tiger Brokers (老虎证券)", "kind": "broker", "notes": "Offshore app broker." },
+    { "code": "PINGAN", "label": "Ping An Insurance (中国平安)", "kind": "insurer", "notes": "Life + P&C; largest insurer." },
+    { "code": "CHINALIFE", "label": "China Life (中国人寿)", "kind": "insurer", "notes": "State-owned life leader." },
+    { "code": "CPIC", "label": "China Pacific Insurance (太平洋保险)", "kind": "insurer" },
+    { "code": "PICC", "label": "People's Insurance Company of China (人保)", "kind": "insurer", "notes": "P&C leader; state-owned." },
+    { "code": "TAIKANG", "label": "Taikang Insurance (泰康保险)", "kind": "insurer", "notes": "Life and pensions." },
+    { "code": "STA", "label": "State Taxation Administration (税务总局)", "kind": "gov", "notes": "Individual income tax (IIT) withholding and filings." },
+    { "code": "SIO", "label": "Social Insurance (社保)", "kind": "gov", "notes": "Pension/medical/unemployment contributions on payslips." },
+    { "code": "HPF", "label": "Housing Provident Fund (公积金)", "kind": "gov", "notes": "Mandatory housing savings; employer-matched." },
+    { "code": "CHINAMOBILE", "label": "China Mobile (中国移动)", "kind": "telco" },
+    { "code": "CHINAUNICOM", "label": "China Unicom (中国联通)", "kind": "telco" },
+    { "code": "CHINATELECOM", "label": "China Telecom (中国电信)", "kind": "telco" },
+    { "code": "STATEGRID", "label": "State Grid (国家电网)", "kind": "utility", "notes": "Electricity for most provinces." },
+    { "code": "CSG", "label": "China Southern Power Grid (南方电网)", "kind": "utility", "notes": "Electricity for the five southern provinces." }
+  ]
+}

package/datasets/institutions/jp.json

@@ -0,0 +1,59 @@
+{
+  "country": "JP",
+  "institutions": [
+    { "code": "MUFG", "label": "MUFG Bank (三菱UFJ銀行)", "kind": "bank", "notes": "Largest megabank." },
+    { "code": "SMBC", "label": "Sumitomo Mitsui Banking Corporation (三井住友銀行)", "kind": "bank", "notes": "Megabank." },
+    { "code": "MIZUHO", "label": "Mizuho Bank (みずほ銀行)", "kind": "bank", "notes": "Megabank." },
+    { "code": "RESONA", "label": "Resona Bank (りそな銀行)", "kind": "bank" },
+    { "code": "YUCHO", "label": "Japan Post Bank (ゆうちょ銀行)", "kind": "bank", "notes": "Largest deposit base; postal network." },
+    { "code": "RAKUTEN-BANK", "label": "Rakuten Bank (楽天銀行)", "kind": "bank", "notes": "Online-only; largest digital bank." },
+    { "code": "SBI-SHINSEI", "label": "SBI Shinsei Bank (SBI新生銀行)", "kind": "bank", "notes": "Former Shinsei; SBI-owned since 2021." },
+    { "code": "SONYBANK", "label": "Sony Bank (ソニー銀行)", "kind": "bank", "notes": "Online-only; FX-friendly." },
+    { "code": "PAYPAY-BANK", "label": "PayPay Bank (PayPay銀行)", "kind": "bank", "notes": "Former Japan Net Bank; SoftBank/Z group." },
+    { "code": "JIBUN", "label": "au Jibun Bank (auじぶん銀行)", "kind": "bank", "notes": "KDDI + MUFG online bank." },
+    { "code": "SEVENBANK", "label": "Seven Bank (セブン銀行)", "kind": "bank", "notes": "ATM network in 7-Eleven stores." },
+    { "code": "JCB", "label": "JCB", "kind": "card_issuer", "notes": "Japan's domestic card network and issuer." },
+    { "code": "RAKUTEN-CARD", "label": "Rakuten Card (楽天カード)", "kind": "card_issuer", "notes": "Largest issuer by cards in force." },
+    { "code": "SAISON", "label": "Credit Saison (クレディセゾン)", "kind": "card_issuer" },
+    { "code": "SMCC", "label": "Sumitomo Mitsui Card (三井住友カード)", "kind": "card_issuer", "notes": "SMBC group; Visa-centric." },
+    { "code": "ORICO", "label": "Orient Corporation (オリコ)", "kind": "card_issuer", "notes": "Cards and shopping credit." },
+    { "code": "AEON-JP", "label": "AEON Financial Service (イオンカード)", "kind": "card_issuer", "notes": "Retail-linked; distinct from AEON Thailand." },
+    { "code": "VIEWCARD", "label": "View Card (ビューカード)", "kind": "card_issuer", "notes": "JR East; Suica auto-charge." },
+    { "code": "PAYPAY", "label": "PayPay", "kind": "wallet", "notes": "Dominant QR wallet; SoftBank/Z group." },
+    { "code": "RAKUTEN-PAY", "label": "Rakuten Pay (楽天ペイ)", "kind": "wallet" },
+    { "code": "DBARAI", "label": "d Barai (d払い)", "kind": "wallet", "notes": "NTT Docomo; can settle via phone bill." },
+    { "code": "AUPAY", "label": "au PAY", "kind": "wallet", "notes": "KDDI." },
+    { "code": "MERPAY", "label": "Merpay (メルペイ)", "kind": "wallet", "notes": "Mercari's wallet." },
+    { "code": "SUICA", "label": "Suica", "kind": "wallet", "notes": "JR East transit IC money; also PASMO interoperable." },
+    { "code": "ZENGIN", "label": "Zengin System (全銀システム)", "kind": "payment_rail", "notes": "Interbank transfer rail; furikomi descriptors." },
+    { "code": "NOMURA", "label": "Nomura Securities (野村證券)", "kind": "broker", "notes": "Largest full-service broker." },
+    { "code": "DAIWA", "label": "Daiwa Securities (大和証券)", "kind": "broker" },
+    { "code": "SBI-SEC", "label": "SBI Securities (SBI証券)", "kind": "broker", "notes": "Largest online broker." },
+    { "code": "RAKUTEN-SEC", "label": "Rakuten Securities (楽天証券)", "kind": "broker", "notes": "Online; NISA-popular." },
+    { "code": "MONEX", "label": "Monex Securities (マネックス証券)", "kind": "broker" },
+    { "code": "MATSUI", "label": "Matsui Securities (松井証券)", "kind": "broker" },
+    { "code": "KABUCOM", "label": "au Kabucom Securities (auカブコム証券)", "kind": "broker", "notes": "MUFG + KDDI." },
+    { "code": "BITFLYER", "label": "bitFlyer", "kind": "crypto_exchange", "notes": "FSA-licensed; largest by BTC volume." },
+    { "code": "COINCHECK", "label": "Coincheck", "kind": "crypto_exchange", "notes": "Monex group." },
+    { "code": "GMOCOIN", "label": "GMO Coin (GMOコイン)", "kind": "crypto_exchange" },
+    { "code": "BITBANK", "label": "bitbank", "kind": "crypto_exchange" },
+    { "code": "SBIVC", "label": "SBI VC Trade", "kind": "crypto_exchange", "notes": "SBI group." },
+    { "code": "NIPPONLIFE", "label": "Nippon Life (日本生命)", "kind": "insurer", "notes": "Life; largest mutual." },
+    { "code": "DAIICHILIFE", "label": "Dai-ichi Life (第一生命)", "kind": "insurer", "notes": "Life; listed." },
+    { "code": "MEIJIYASUDA", "label": "Meiji Yasuda Life (明治安田生命)", "kind": "insurer" },
+    { "code": "SUMITOMOLIFE", "label": "Sumitomo Life (住友生命)", "kind": "insurer" },
+    { "code": "TOKIO-MARINE-JP", "label": "Tokio Marine & Nichido (東京海上日動)", "kind": "insurer", "notes": "Non-life leader; parent of Tokio Marine Thailand." },
+    { "code": "SOMPO", "label": "Sompo Japan (損保ジャパン)", "kind": "insurer", "notes": "Non-life." },
+    { "code": "NTA", "label": "National Tax Agency (国税庁)", "kind": "gov", "notes": "Income tax; nenmatsu-chosei year-end adjustment." },
+    { "code": "NENKIN", "label": "Japan Pension Service (日本年金機構)", "kind": "gov", "notes": "National and employee pension contributions." },
+    { "code": "DOCOMO", "label": "NTT Docomo", "kind": "telco" },
+    { "code": "KDDI", "label": "au (KDDI)", "kind": "telco" },
+    { "code": "SOFTBANK", "label": "SoftBank", "kind": "telco" },
+    { "code": "RAKUTEN-MOBILE", "label": "Rakuten Mobile (楽天モバイル)", "kind": "telco" },
+    { "code": "TEPCO", "label": "Tokyo Electric Power (東京電力)", "kind": "utility", "notes": "Kanto electricity." },
+    { "code": "KEPCO-JP", "label": "Kansai Electric Power (関西電力)", "kind": "utility", "notes": "Kansai electricity." },
+    { "code": "CHUBU", "label": "Chubu Electric Power (中部電力)", "kind": "utility" },
+    { "code": "TOKYOGAS", "label": "Tokyo Gas (東京ガス)", "kind": "utility" },
+    { "code": "OSAKAGAS", "label": "Osaka Gas (大阪ガス)", "kind": "utility" }
+  ]
+}