docs: add TODO.md with known gaps & follow-ups; link from CLAUDE.md

Tracks verification gaps and deferred items surfaced while live-validating the
SDK, kept separate from the high-level roadmap. Records the live-verified finding
that credit notes cannot be created in test mode (the test-mode original is not
retrievable), so NC works on real documents only.

Author: bilouro

CLAUDE.md

@@ -432,6 +432,10 @@ Note: the client object is NOT returned. If the SDK needs the client id, it must
 | v0.6.0 | CLI tool + dry-run mode | — |
 | v1.0.0 | Stable API, full docs | — |
 
+**Known gaps & follow-ups** (verification gaps, deferred features, correctness TODOs)
+are tracked in [`TODO.md`](TODO.md) at the repo root — consult it before starting
+related work, and keep it honest (check items only when actually verified/done).
+
 ---
 
 ## Authoring & Attribution

TODO.md

@@ -0,0 +1,66 @@
+# TODO — known gaps & follow-ups
+
+Running list of concrete follow-ups and known gaps, complementing the high-level
+[Roadmap](CLAUDE.md#roadmap). Most items here were surfaced by **live-validating
+the SDK against the real Vendus API** — they record what is *not* yet verified or
+done, so nothing is silently assumed. Keep this honest: only check an item when it
+is actually done/verified, not just coded.
+
+## Live-validation gaps
+
+- [ ] **Run `create_credit_note` through the SDK end-to-end live in REAL mode.** It is
+  validated by unit tests (wire body) plus a manual raw-HTTP call that succeeded
+  (NC 01P2026/9). The SDK method has been fired live only in **test** mode, where it
+  correctly fails (`NotFoundError`, see next item). Do one real FT/FR →
+  `create_credit_note(...)` cycle to confirm the SDK builds a working real NC.
+- [x] **NC in test mode is verified impossible.** `create_credit_note` on a test-mode
+  FT or FR fails with `NotFoundError` ("No data") because the original test document
+  is not retrievable via `/documents/{id}`. NC only works on real, retrievable
+  originals. (Verified live for both FT and FR.)
+- [ ] **Clearer error when crediting a non-retrievable original.** The GET inside
+  `create_credit_note` raises a generic `NotFoundError`; wrap it with a hint that the
+  original must be a real (non-test) document. Cannot distinguish "test doc" from
+  "genuinely missing" (both 404), so keep it a hint, not a hard claim.
+- [ ] **Multi-line credit notes.** `document_row` is only verified for a single-line
+  original (row=1). The builder assumes `row = 1-based position`; verify against a
+  real multi-line invoice.
+- [ ] **`mode=tests` override on a `normal` register.** Unverified whether a per-request
+  `mode=tests` produces a non-fiscal document on a register configured as `normal`.
+  Our register is in `tests` mode, so we never exercised the override direction.
+- [ ] **FR payment variations.** Only validated with cash (type `NU`). Not tested:
+  other methods (MB/MBWAY/CC…), multiple `payments`, and deferred `date_due`.
+
+## SDK gaps / decisions to revisit
+
+- [ ] **Partial credit notes.** Vendus supports crediting part of a document
+  (`qty_nc` per line). The SDK only does **full** credit in v0.1. Add a partial API
+  (select lines/quantities) when needed.
+- [ ] **`cancel` for non-FT/FR/NC types.** The SDK blocks the three fiscal types we
+  know are non-cancellable (FT verified; FR/NC by rule). Which other types Vendus
+  actually lets you cancel is unverified — do not expand the block list without
+  checking. Consider also translating Vendus's "não é permitido cancelar" error as a
+  backstop.
+- [ ] **`DocumentType` enum vs the authoritative `documents/types` list.** The enum
+  still has `OR` and `RC`, which are absent from the reference list
+  (FT/FS/NC/FR/FG/ND/GA/GD/GR/GT/DC/PF/OT/EC). The live account also returns `RG`,
+  which is in *no* list. Decide: align the enum to the reference (likely `QUOTE` →
+  `OT`, add the missing codes) and how to model `RG`. Unknown codes already fall back
+  to `DocumentType.UNKNOWN`, so this is correctness/ergonomics, not a crash risk.
+
+## Robustness / correctness
+
+- [ ] **Error mapping by code, not just HTTP status.** Vendus returns HTTP 403 for some
+  validation errors (e.g. `P001`) and 400 for others. The transport maps 403 →
+  `AuthorizationError`, which is misleading for a field-validation error. Map known
+  error codes (P001, A001, …) to clearer exceptions.
+- [ ] **Stronger non-fiscal assertion in the FR/FT integration tests.** `tax_authority_id`
+  is empty in the POST response even for *real* fiscal documents, so it is necessary
+  but not sufficient proof of non-fiscality. The real discriminator is the series
+  prefix (`FT T01P…` test vs `FT 01P…` real) — consider asserting on it.
+
+## Docs
+
+- [ ] **Document `list_payment_methods` and the `Payment` model** on a dedicated docs
+  page (currently only shown inline in the FR examples).
+- [ ] **Mention the cancel restriction prominently** in the getting-started flow (FT/FR
+  can't be cancelled → credit note), not only on the per-document pages.