Sync Repo-docs-fints from project files

Repo-docs-fints.-.md

@@ -0,0 +1,140 @@
+<!-- codex-wiki-sync:fb86e4495353ece8031bd63c -->
+
+> Mirrored from `/mnt/DATA/git/mousehold/docs/fints.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# FinTS Connector
+
+The FinTS connector can run embedded in the main API or in the separate local
+agent. Embedded mode is the default for local/self-hosted installs, so users do
+not need to start a second process.
+
+The privacy tradeoff is explicit:
+
+- Embedded mode: the API process receives PIN/TAN inputs while a FinTS job runs.
+- Separate local-agent mode: PIN/TAN inputs stay in the separate local process.
+
+In both modes, PINs are not stored in the database. Normalized observations are
+stored only when you import them.
+
+## Required Inputs
+
+- `--blz` or `MOUSEHOLD_FINTS_BLZ`: bank identifier/BLZ.
+- `--server` or `MOUSEHOLD_FINTS_SERVER`: FinTS endpoint URL.
+- `--bank-user-id` or `MOUSEHOLD_FINTS_USER_ID`: your bank login ID.
+- PIN: prompted interactively by default, or provided through `MOUSEHOLD_FINTS_PIN`.
+- `--product-id` or `MOUSEHOLD_FINTS_PRODUCT_ID`: required by python-fints 4+.
+  Register a product ID with Deutsche Kreditwirtschaft/ZKA before connecting.
+- Optional `--customer-id`, `--tan-medium`, and `--product-version`.
+
+## comdirect
+
+The web UI has a `comdirect` preset.
+
+Current values:
+
+```text
+BLZ: 20041111
+FinTS endpoint: https://fints.comdirect.de/fints
+Bank user ID: your comdirect Zugangsnummer
+Customer ID: leave empty
+```
+
+If your account uses a different comdirect/Commerzbank GF comdirect BLZ, replace
+the preset BLZ before fetching accounts.
+
+## Local State
+
+The connector stores non-PIN client state in:
+
+```text
+~/.config/mousehold/fints/<profile>.json
+```
+
+This caches bank parameter data, selected TAN mechanism, and selected TAN
+medium so repeated syncs do not ask the same setup questions. The file is
+written with mode `0600`.
+
+Use `--no-state` for a one-off session without reading or writing that cache.
+
+## Commands
+
+The browser UI uses the embedded API route by default:
+
+```text
+http://127.0.0.1:8001/agent/fints/...
+```
+
+To use a separate local-agent HTTP bridge instead:
+
+```sh
+mousehold-agent serve --host 127.0.0.1 --port 8765
+```
+
+Then set `VITE_LOCAL_AGENT_URL=http://127.0.0.1:8765` in
+`apps/web/.env.development`.
+
+List accounts:
+
+```sh
+mousehold-agent fints-accounts \
+  --profile my-bank \
+  --blz <bank-blz> \
+  --server <fints-endpoint-url> \
+  --bank-user-id <bank-login-id> \
+  --with-balances
+```
+
+Display transactions:
+
+```sh
+mousehold-agent fints-transactions \
+  --profile my-bank \
+  --blz <bank-blz> \
+  --server <fints-endpoint-url> \
+  --bank-user-id <bank-login-id> \
+  --iban <iban> \
+  --start-date 2026-06-01 \
+  --end-date 2026-06-27
+```
+
+Sync transactions into Mousehold:
+
+```sh
+mousehold-agent sync-fints \
+  --api-url http://127.0.0.1:8001 \
+  --connection-id <connection-id> \
+  --household-id <household-id> \
+  --owner-user-id <user-id> \
+  --source-account-id <account-id> \
+  --profile my-bank \
+  --blz <bank-blz> \
+  --server <fints-endpoint-url> \
+  --bank-user-id <bank-login-id> \
+  --iban <iban> \
+  --days 30 \
+  --display
+```
+
+## TAN Handling
+
+If the bank returns a TAN challenge, the CLI prints the challenge text and asks
+for the TAN. Decoupled app confirmation flows prompt you to confirm in the
+banking app and press Enter. Binary challenge images are written under:
+
+```text
+~/.config/mousehold/fints/challenges/
+```
+
+## Ledger Mapping
+
+FinTS transactions are imported as `source_type = "fints"` and
+`status = "confirmed"`.
+
+- Positive bank movements become `income`.
+- Ordinary negative bank movements become `expense`.
+- Negative movements mentioning PayPal, Klarna, or credit-card providers become
+  `liability_payment`, so they can later be linked to prior obligations instead
+  of becoming duplicate household expenses.