logos-bancos-br 0.1.0 → 0.3.0

package/README.en.md

@@ -1,8 +1,10 @@
 # logos-bancos-br
 
-> **Brazilian bank list + official logos, always up to date.** Everything is derived from
-> official sources only (Central Bank of Brazil and Open Finance Brasil) and **rebuilt
-> automatically every week by CI** — with verifiable per-logo provenance.
+> **Dataset + logos of Brazil's financial and payment institutions** — banks, fintechs, payment
+> institutions and credit unions — **always up to date**. Everything is derived from three named
+> official sources: the **STR participants list** and the **active Pix participants list**, both
+> from the **Central Bank of Brazil (BCB)**, plus the **Open Finance Brasil participants
+> directory**. Rebuilt automatically every week by CI, with verifiable per-logo provenance.
 > **[Versão em português](README.md)**
 
 [![CI](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml/badge.svg)](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml)
@@ -28,13 +30,17 @@
 
 ## What this package gives you
 
-1. **The list of institutions — auto-updated.** Every institution with a COMPE code in the
-   Central Bank of Brazil STR participants list (currently 470), with official name, short name,
-   COMPE code and ISPB, in [`data/bancos.json`](data/bancos.json). You never hand-maintain a
-   bank list again.
-2. **Official logos.** Currently 107, as 256×256 PNGs (+ SVG when available), sourced from the
-   public **Open Finance Brasil** directory — where each institution publishes and maintains its
-   own brand. Every file carries provenance: source URI, SHA-256 and date.
+1. **The list of institutions — auto-updated.** The union, keyed by ISPB, of two Central Bank
+   lists: STR participants (every institution with a COMPE code, currently 470) and **active Pix
+   participants** (currently ~880, ~640 of which have no COMPE — fintechs, payment institutions,
+   credit unions). **1,113 institutions** in [`data/bancos.json`](data/bancos.json), with
+   official names, COMPE (when it exists), ISPB and Pix participation attributes.
+2. **Official logos.** Currently **473**, as 256×256 PNGs (+ SVG when available), from two
+   origins — both official and identified in the dataset (`logo.source.type`): the public **Open
+   Finance Brasil** directory (`openfinance`) and the **institution's own official website**
+   (`direct-uri`), visually curated before shipping. Affiliates of single-brand cooperative
+   systems (Sicoob, Sicredi, Cresol, Unicred) get the system's logo via a curated brand rule.
+   Every file carries provenance: source URI, SHA-256 and date.
 3. **Automatic updates, no manual curation.** Every Monday a GitHub Action
    ([`update-logos.yml`](.github/workflows/update-logos.yml)) rebuilds **both the list AND the
    logos** from the sources and opens a PR with the visual diff. A bank created, renamed or
@@ -49,8 +55,11 @@ Because it rots: the Central Bank adds, renames and removes institutions through
 and banks redesign their brands. Existing libraries ship either **data only** (no logos) or
 logos **hand-collected** from assorted websites with no traceability. The approach here:
 
-- **Official sources, and only them** — the STR participants CSV (updated daily by the Central
-  Bank itself) and the Open Finance Brasil participants directory. No images "found on Google".
+- **Official sources, and only them** — the STR and Pix participants CSVs (updated daily by the
+  Central Bank itself), the Open Finance Brasil participants directory and, for non-participants,
+  the icon the institution publishes **on its own official website** (hand-reviewed). No images
+  "found on Google" or from aggregators. Open Finance purists can filter:
+  `banks().filter(b => b.logo?.source.type === 'openfinance')`.
 - **Per-logo provenance** — `data/bancos.json` records each logo's source URI, SHA-256 of the
   original artwork and last-change date. The git diff is the audit trail.
 - **Safe matching** — automatic matches happen **only via ISPB** (= first 8 digits of the CNPJ).
@@ -58,9 +67,10 @@ logos **hand-collected** from assorted websites with no traceability. The approa
   In a banking context, a wrong logo is worse than no logo.
 - **Safe assets** — https-only downloads with size/pixel caps; SVGs redistributed only after
   sanitization (no scripts, event handlers, `foreignObject` or external references).
-- **Honest trade-off** — 107 of the 470 institutions have a logo (the Open Finance participants,
-  which cover the vast majority of accounts in Brazil). The rest are small credit unions/SCDs
-  with no officially published logo — your app picks the fallback.
+- **Honest trade-off** — 473 of the 1,113 institutions have a logo (Open Finance participants,
+  cooperative-system affiliates and ~45 institutions covered via official sites — the vast
+  majority of accounts in Brazil). The rest are small SCDs/brokers/payment institutions — your
+  app picks the fallback, and coverage grows every release.
 
 ## Install & use
 
@@ -68,7 +78,14 @@ logos **hand-collected** from assorted websites with no traceability. The approa
 npm install logos-bancos-br
 ```
 
-Files are named by **ISPB** (8 digits). Lookups accept **COMPE or ISPB**.
+Requires **Node ≥ 20** for Node/CLI usage (web and React Native follow your bundler's
+environment). Zero runtime dependencies. Published with **npm provenance** — verify integrity
+with `npm audit signatures`.
+
+Files are named by **ISPB** (8 digits — which is what lets the ~640 COMPE-less Pix institutions
+in). Lookups accept **COMPE or ISPB**; Pix-only institutions have `compe: null` and are
+addressable by ISPB. Each bank carries a `pix` block (participation attributes, verbatim from
+the BCB list) or `null`.
 
 ```ts
 import { banks, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
@@ -78,7 +95,8 @@ byIspb('00000000');  // Banco do Brasil
 logoCdnUrl(341);     // https://cdn.jsdelivr.net/npm/logos-bancos-br@x.y.z/logos/png/60701190.png
 ```
 
-**React Native (Expo/Metro)** — static require() map (bundles all logos, ~1.3 MB):
+**React Native (Expo/Metro)** — static require() map (bundles all logos, ~4 MB; keys accept both the
+4-digit COMPE and the 8-digit ISPB — Pix-only institutions by ISPB only):
 
 ```tsx
 import logos from 'logos-bancos-br/react-native';
@@ -102,7 +120,7 @@ npx logos-bancos-br list
 **CDN, no install** (always pin a version):
 
 ```
-https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/png/60701190.png
+https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/png/60701190.png
 ```
 
 **Data only** (the bank list):
@@ -111,6 +129,23 @@ https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/png/60701190.png
 import data from 'logos-bancos-br/data/bancos.json';
 ```
 
+### API quick reference
+
+| Import | Function | Returns |
+|---|---|---|
+| `logos-bancos-br` | `banks()` | every institution (`Bank[]`) |
+| | `byCompe(code)` | `Bank \| undefined` — `341`, `'341'` and `'0341'` are equivalent |
+| | `byIspb(ispb)` | `Bank \| undefined` |
+| | `findBank(code)` | `Bank \| undefined` — more than 4 digits is treated as ISPB |
+| | `logoCdnUrl(code, { format?, version? })` | jsDelivr URL, or `null` when there is no logo |
+| | `normalizeCompe(x)` · `normalizeIspb(x)` | `'0341'` · `'60701190'` |
+| | `version` | package version (string) |
+| `logos-bancos-br/node` | `logoPngPath(code)` · `logoSvgPath(code)` | absolute asset path, or `null` |
+| | `copyLogos({ dest, format?, by?, only? })` | copies assets into a directory (what the CLI uses) |
+| `logos-bancos-br/react-native` | `logos` (default export) | require() map keyed by COMPE4 **and** ISPB |
+
+Exported TypeScript types: `Bank`, `BankLogo`, `BankLogoSource`, `PixInfo`.
+
 ## Dataset shape
 
 ```json
@@ -120,6 +155,7 @@ import data from 'logos-bancos-br/data/bancos.json';
   "compe4": "0341",
   "name": "Itaú Unibanco S.A.",
   "shortName": "ITAÚ UNIBANCO S.A.",
+  "pix": { "spiParticipationType": "Direta", "pixParticipationType": "Obrigatória", "modality": "Provedor de Conta Transacional", "institutionType": "Banco Múltiplo", "authorizedByBcb": true },
   "logo": {
     "png": "logos/png/60701190.png",
     "svg": "logos/svg/60701190.svg",
@@ -129,16 +165,23 @@ import data from 'logos-bancos-br/data/bancos.json';
 ```
 
 `logo.png` is a normalized transparent 256×256 PNG; `logo.svg` is the original vector when safely
-redistributable; `logo: null` means the institution has no logo in the official sources.
+redistributable; `logo: null` means the institution has no logo in the official sources; `compe: null` marks a
+Pix-only institution (address it by ISPB); `pix: null` marks a non-Pix participant.
 
 ## How the auto-update works
 
-The pipeline joins the STR list (which institutions exist) with the Open Finance directory
-(their logos), bridged by `ISPB == first 8 digits of the CNPJ`; hand-reviewed `forcedMatches`
-cover second brands (XP CCTVM, Nu Invest, Bradesco BBI…). The weekly workflow regenerates
+The pipeline unions the Central Bank's STR and active-Pix participants lists (which institutions
+exist, keyed by ISPB) and joins them with the Open Finance directory (their logos), bridged by
+`ISPB == first 8 digits of the CNPJ`; hand-reviewed `forcedMatches` cover second brands (XP
+CCTVM, Nu Invest, Bradesco BBI…), and a curated brand rule gives cooperative-system affiliates
+(Sicoob/Sicredi/Cresol/Unicred) their system's logo. For institutions outside Open Finance,
+discovery tools (`npm run discover` / `discover:ai`) find the icon published on the institution's
+official website — nothing ships without visual curation (brand + domain reviewed); approvals
+become `forcedUris` (`source.type: "direct-uri"`). The weekly workflow regenerates
 `data/bancos.json`, `logos/`, `PREVIEW.md` and `react-native.js` and opens a PR with the report
-and the visual PNG diff. After review and merge, a new version is published to npm. Nothing is
-edited by hand. Maintenance details: [CONTRIBUTING.md](CONTRIBUTING.md).
+and the visual PNG diff. After review and merge, the maintainer publishes a new version to npm
+(GitHub Release). Nothing is edited by hand. Maintenance details:
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Trademarks
 

package/README.md

@@ -1,8 +1,11 @@
 # logos-bancos-br
 
-> **Lista de bancos brasileiros + logos oficiais, sempre atualizados.** Tudo derivado de fontes
-> 100% oficiais (Banco Central e Open Finance Brasil) e **reconstruído automaticamente toda
-> semana por CI** — com proveniência verificável por logo. **[English version](README.en.md)**
+> **Dataset + logos das instituições financeiras e de pagamento do Brasil** — bancos, fintechs,
+> IPs e cooperativas — **sempre atualizados**. Tudo derivado de três fontes 100% oficiais e
+> nomeadas: a **lista de participantes do STR** e a **lista de participantes ativos do Pix**,
+> ambas do **Banco Central do Brasil**, e o **diretório de participantes do Open Finance
+> Brasil**. Reconstruído automaticamente toda semana por CI, com proveniência verificável por
+> logo. **[English version](README.en.md)**
 
 [![CI](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml/badge.svg)](https://github.com/rzmt/logos-bancos-br/actions/workflows/ci.yml)
 [![atualização](https://github.com/rzmt/logos-bancos-br/actions/workflows/update-logos.yml/badge.svg)](https://github.com/rzmt/logos-bancos-br/actions/workflows/update-logos.yml)
@@ -27,13 +30,18 @@
 
 ## O que este pacote entrega
 
-1. **A lista de instituições — atualizada automaticamente.** Todas as instituições com código
-   COMPE da lista de participantes do STR do **Banco Central** (hoje 470), com nome oficial,
-   nome reduzido, código COMPE e ISPB, em [`data/bancos.json`](data/bancos.json). Você nunca
-   mais mantém uma lista de bancos à mão.
-2. **Logos oficiais.** Hoje 107, em PNG 256×256 (+ SVG quando disponível), vindos do diretório
-   público do **Open Finance Brasil** — onde cada instituição publica e mantém a própria marca.
-   Cada arquivo carrega proveniência: URI de origem, SHA-256 e data.
+1. **A lista de instituições — atualizada automaticamente.** A união, por ISPB, de duas listas
+   do **Banco Central**: participantes do STR (todas as instituições com código COMPE, hoje 470)
+   e **participantes ativos do Pix** (hoje ~880, das quais ~640 não têm COMPE — fintechs, IPs e
+   cooperativas). São **1.113 instituições** em [`data/bancos.json`](data/bancos.json), com nome
+   oficial, nome reduzido, COMPE (quando existe), ISPB e os atributos de participação no Pix.
+   Você nunca mais mantém uma lista de bancos à mão.
+2. **Logos oficiais.** Hoje **473**, em PNG 256×256 (+ SVG quando disponível), de duas origens —
+   ambas oficiais e identificadas no dataset (`logo.source.type`): o diretório público do
+   **Open Finance Brasil** (`openfinance`), onde cada instituição publica a própria marca, e o
+   **site oficial da própria instituição** (`direct-uri`), com curadoria visual antes de entrar.
+   Afiliadas de sistemas cooperativos de marca única (Sicoob, Sicredi, Cresol, Unicred) recebem
+   o logo do sistema por regra curada. Cada arquivo carrega proveniência: URI, SHA-256 e data.
 3. **Atualização automática, sem curadoria manual.** Toda segunda-feira um GitHub Action
    ([`update-logos.yml`](.github/workflows/update-logos.yml)) reconstrói **a lista E os logos**
    a partir das fontes e abre um PR com o diff visual. Banco criado, renomeado ou extinto pelo
@@ -48,9 +56,11 @@ Porque ela envelhece: o BCB inclui, renomeia e exclui instituições ao longo do
 redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem logos), ou logos
 **coletados manualmente** de sites variados, sem rastreabilidade. A abordagem aqui:
 
-- **Fontes oficiais, e apenas elas** — o CSV de participantes do STR (que o próprio BCB atualiza
-  diariamente) e o diretório de participantes do Open Finance Brasil. Nenhuma imagem "achada no
-  Google".
+- **Fontes oficiais, e apenas elas** — os CSVs de participantes do STR e do Pix (que o próprio
+  BCB atualiza diariamente), o diretório de participantes do Open Finance Brasil e, para quem não
+  participa do Open Finance, o ícone que a própria instituição publica **no site oficial dela**
+  (revisado à mão). Nenhuma imagem "achada no Google" ou de agregador. Quem quiser só a fonte
+  Open Finance filtra: `banks().filter(b => b.logo?.source.type === 'openfinance')`.
 - **Proveniência por logo** — `data/bancos.json` registra a URI de origem, o SHA-256 do arquivo
   original e a data de cada logo. O diff do git é a auditoria.
 - **Correspondência segura** — match automático **somente por ISPB** (= raiz do CNPJ).
@@ -59,9 +69,10 @@ redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem l
 - **Assets seguros** — download só via https com teto de tamanho e de pixels; SVGs
   redistribuídos apenas após sanitização (sem `script`, event handlers, `foreignObject` ou
   referências externas).
-- **Trade-off honesto** — 107 das 470 instituições têm logo (as participantes do Open Finance,
-  que cobrem a esmagadora maioria das contas do país). As demais são SCDs/cooperativas pequenas
-  sem logo oficial publicado; para elas seu app usa o fallback que preferir.
+- **Trade-off honesto** — 473 das 1.113 instituições têm logo (participantes do Open Finance,
+  afiliadas dos sistemas cooperativos e ~45 instituições cobertas pelos sites oficiais — a
+  esmagadora maioria das contas do país). As demais são SCDs/corretoras/IPs pequenas; para elas
+  seu app usa o fallback que preferir — e a cobertura cresce a cada release.
 
 ## Instalação e uso
 
@@ -69,8 +80,12 @@ redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem l
 npm install logos-bancos-br
 ```
 
-Os arquivos são nomeados pelo **ISPB** (8 dígitos, estável e universal — inclusive para
-instituições Pix sem COMPE, no roadmap). As consultas aceitam **COMPE ou ISPB**.
+Requer **Node ≥ 20** para uso via Node/CLI (em web e React Native vale o ambiente do seu
+bundler). Zero dependências de runtime. Publicado com **npm provenance** — verifique a
+integridade com `npm audit signatures`.
+
+Os arquivos são nomeados pelo **ISPB** (8 dígitos, estável e universal — é o que permite cobrir
+as ~640 instituições do Pix que não têm código COMPE). As consultas aceitam **COMPE ou ISPB**.
 
 ### JavaScript / TypeScript (Node ou web)
 
@@ -80,8 +95,12 @@ import { banks, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
 byCompe(341);        // { ispb: '60701190', compe4: '0341', name: 'Itaú Unibanco S.A.', logo: {...} }
 byCompe('0260');     // Nubank — '260', 260 e '0260' são equivalentes
 byIspb('00000000');  // Banco do Brasil
+byIspb('11275560');  // RecargaPay — instituição só-Pix (compe: null), endereçável por ISPB
 
 logoCdnUrl(341);     // https://cdn.jsdelivr.net/npm/logos-bancos-br@x.y.z/logos/png/60701190.png
+
+// Atributos de participação no Pix (verbatim da lista do BCB):
+byCompe(341)?.pix;   // { spiParticipationType: 'Direta', pixParticipationType: 'Obrigatória', ... }
 ```
 
 ### React (web)
@@ -100,8 +119,10 @@ import logos from 'logos-bancos-br/react-native'; // mapa require() estático
 <Image source={logos[codigoBanco.padStart(4, '0')]} style={{ width: 40, height: 40 }} />
 ```
 
-> Importar esse entry adiciona **todos** os logos (~1,3 MB) ao bundle. Se preferir empacotar só
-> alguns, use o CLI abaixo e faça `require()` dos arquivos copiados.
+> As chaves do mapa aceitam o COMPE com 4 dígitos (`'0341'`) **e** o ISPB (`'60701190'`;
+> instituições só-Pix aparecem apenas pelo ISPB). Importar esse entry adiciona **todos** os
+> logos (~4 MB) ao bundle. Se preferir empacotar só alguns, use o CLI abaixo e faça `require()`
+> dos arquivos copiados.
 
 ### Node (caminho dos arquivos no disco)
 
@@ -116,8 +137,8 @@ logoPngPath('341'); // /…/node_modules/logos-bancos-br/logos/png/60701190.png
 Vendorize os assets no seu projeto — sem dependência de runtime:
 
 ```bash
-npx logos-bancos-br copy --dest ./assets/banks            # 0341.png, 0001.png, ... (por COMPE)
-npx logos-bancos-br copy --dest ./assets/banks --by ispb  # 60701190.png, ...
+npx logos-bancos-br copy --dest ./assets/banks            # 0341.png, ... (por COMPE; só-Pix ficam de fora)
+npx logos-bancos-br copy --dest ./assets/banks --by ispb  # 60701190.png, ... (todas, incl. só-Pix)
 npx logos-bancos-br copy --dest ./assets/banks --format both --only 341,001,260
 npx logos-bancos-br list                                  # tabela COMPE · ISPB · nome · tem logo
 ```
@@ -127,20 +148,38 @@ Rode de novo a cada atualização do pacote para receber lista e logos novos.
 ### CDN — sem instalar nada
 
 ```
-https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/png/60701190.png
-https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/svg/18236120.svg
+https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/png/60701190.png
+https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/svg/18236120.svg
 ```
 
-Fixe sempre uma versão (`@0.1.0`) — a correspondência COMPE→ISPB está em
+Fixe sempre uma versão (`@0.3.0`) — a correspondência COMPE→ISPB está em
 [`data/bancos.json`](data/bancos.json).
 
 ### Só os dados (lista de bancos)
 
 ```ts
 import dados from 'logos-bancos-br/data/bancos.json';
-// todas as instituições: ispb, compe, compe4, nome oficial, nome reduzido, logo (ou null)
+// todas as instituições: ispb, compe/compe4 (ou null p/ só-Pix), nomes oficiais,
+// pix (atributos de participação, ou null) e logo (ou null)
 ```
 
+### Referência rápida da API
+
+| Import | Função | Retorna |
+|---|---|---|
+| `logos-bancos-br` | `banks()` | todas as instituições (`Bank[]`) |
+| | `byCompe(codigo)` | `Bank \| undefined` — `341`, `'341'` e `'0341'` são equivalentes |
+| | `byIspb(ispb)` | `Bank \| undefined` |
+| | `findBank(codigo)` | `Bank \| undefined` — mais de 4 dígitos trata como ISPB |
+| | `logoCdnUrl(codigo, { format?, version? })` | URL do jsDelivr, ou `null` se não houver logo |
+| | `normalizeCompe(x)` · `normalizeIspb(x)` | `'0341'` · `'60701190'` |
+| | `version` | versão do pacote (string) |
+| `logos-bancos-br/node` | `logoPngPath(codigo)` · `logoSvgPath(codigo)` | caminho absoluto do asset, ou `null` |
+| | `copyLogos({ dest, format?, by?, only? })` | copia os assets para um diretório (o que o CLI usa) |
+| `logos-bancos-br/react-native` | `logos` (default export) | mapa `require()` com chaves COMPE4 **e** ISPB |
+
+Tipos TypeScript exportados: `Bank`, `BankLogo`, `BankLogoSource`, `PixInfo`.
+
 ## O dataset
 
 Um registro de `data/bancos.json`:
@@ -152,6 +191,13 @@ Um registro de `data/bancos.json`:
   "compe4": "0341",
   "name": "Itaú Unibanco S.A.",
   "shortName": "ITAÚ UNIBANCO S.A.",
+  "pix": {
+    "spiParticipationType": "Direta",
+    "pixParticipationType": "Obrigatória",
+    "modality": "Provedor de Conta Transacional",
+    "institutionType": "Banco Múltiplo",
+    "authorizedByBcb": true
+  },
   "logo": {
     "png": "logos/png/60701190.png",
     "svg": "logos/svg/60701190.svg",
@@ -169,37 +215,52 @@ Um registro de `data/bancos.json`:
 
 - `logo.png` — PNG normalizado **256×256**, fundo transparente, `fit: contain`.
 - `logo.svg` — vetor original, presente só quando passa na sanitização.
-- `logo.source` — proveniência completa: de onde veio, hash e quando mudou.
+- `logo.source` — proveniência completa: de onde veio, hash e quando mudou. `source.type`:
+  `openfinance` (diretório Open Finance, match automático por ISPB ou revisado), `direct-uri`
+  (URL no site oficial da instituição, revisada à mão) ou `override` (arte mantida no repo).
 - `logo: null` — instituição sem logo nas fontes oficiais (use seu fallback).
+- `compe`/`compe4: null` — instituição só-Pix (sem código COMPE); endereçe por ISPB.
+- `pix` — atributos verbatim da lista de participantes ativos do Pix do BCB (tipo de
+  participação no SPI e no Pix, modalidade, tipo de instituição, autorizada pelo BCB);
+  `null` quando a instituição não é participante ativa do Pix.
 
 ## Como funciona a atualização automática
 
-1. **Espinha dorsal**: o CSV público de participantes do STR do Banco Central define *quais
-   instituições existem* (ISPB + COMPE + nomes oficiais). O BCB atualiza esse arquivo
-   diariamente.
+1. **Espinha dorsal**: a união, por ISPB, de dois CSVs públicos do Banco Central — a lista de
+   participantes do STR (`ParticipantesSTR.csv`: ISPB + COMPE + nomes oficiais) e a **lista de
+   participantes ativos do Pix** (arquivo diário datado, que acrescenta as instituições sem
+   COMPE e os atributos de participação). Ambos atualizados diariamente pelo BCB.
 2. **Logos**: o diretório público de participantes do Open Finance Brasil traz, por CNPJ, o logo
    que cada instituição publica para ser exibido por terceiros.
 3. **Ponte**: `ISPB == 8 primeiros dígitos do CNPJ` (é assim que o BCB os atribui na esmagadora
    maioria dos casos). Quando não bate — segundas marcas como XP CCTVM, Nu Invest, Bradesco BBI —
    entra o `forcedMatches`, revisado à mão a partir das sugestões do relatório.
-4. **Normalização**: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
-5. **Cadência**: o workflow roda **toda segunda-feira** (e sob demanda), regenera
+4. **Sistemas cooperativos**: afiliadas que carregam a marca do sistema no nome oficial
+   (Sicoob, Sicredi, Cresol, Unicred) recebem o logo do sistema por regra curada — explícita e
+   auditável, não semelhança fuzzy.
+5. **Fora do Open Finance**: ferramentas de descoberta (`npm run discover` e `discover:ai`)
+   acham o ícone publicado no site oficial da instituição; **nada entra sem curadoria visual**
+   (o revisor confere marca e domínio) — aprovados viram `forcedUris`.
+6. **Normalização**: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
+7. **Cadência**: o workflow roda **toda segunda-feira** (e sob demanda), regenera
    `data/bancos.json`, `logos/`, `PREVIEW.md` e `react-native.js`, e **abre um PR** com o
-   relatório e o diff visual dos PNGs. Depois da revisão e merge, uma nova versão vai para o
-   npm. Nada é editado à mão.
+   relatório e o diff visual dos PNGs. Depois da revisão e merge, o mantenedor publica uma
+   nova versão no npm (Release no GitHub). Nada é editado à mão.
 
 Detalhes de manutenção (rodar o pipeline localmente, promover sugestões, overrides, denylist):
 **[CONTRIBUTING.md](CONTRIBUTING.md)**.
 
 ## Limitações conhecidas
 
-- Cobertura de logos = instituições ativas no Open Finance com URL de logo válida. Hoje são 107;
-  o número cresce conforme o ecossistema.
+- Cobertura de logos: 473 de 1.113 hoje (Open Finance + regra de marca cooperativa + sites
+  oficiais curados); cresce conforme o ecossistema e a curadoria. **Sua instituição está sem
+  logo?** Abra uma issue com o template "Sugestão de match"/"Adicionar logo" apontando a URL no
+  domínio oficial — promovemos rápido.
 - Algumas instituições publicam no diretório o logo da sua **marca de produto** (ex.: Banco CSF →
   cartão Atacadão). É a escolha oficial da própria instituição; se preferir outra arte no seu app,
   use um override local seu.
-- Instituições **sem** código COMPE (participantes só do Pix) ainda não entram — o naming por ISPB
-  já foi desenhado para recebê-las sem breaking change (roadmap).
+- Instituições em processo de **adesão** ao Pix (segunda seção da lista do BCB) e participantes
+  sem ISPB publicado (18 hoje) não entram — só participantes ativos com ISPB.
 
 ## Marcas e remoção