Vink — lichtgewicht ZZP-administratie met Claude Code

English: Vink is a Claude Code plugin for Dutch freelancers (ZZP'ers): invoices, receipts,
quarterly VAT returns and year-end figures, kept as plain CSV/JSON files in your own folder. The
skills decide what to record; a deterministic Node CLI does the invoice numbering, VAT math,
currency conversion and PDF rendering. Docs and skills are in Dutch; invoices and the dashboard
render in Dutch or English.

Een lichtgewicht administratie voor Nederlandse ZZP'ers/freelancers, volledig op platte
bestanden (CSV + JSON) en aangedreven door Claude Code.
Je praat in gewone taal ("maak een factuur voor klant X", "verwerk deze bon"); de skills
redeneren en stellen voor, en een klein deterministisch programma (lib/admin.mjs) doet het
exacte rekenwerk en schrijft naar de bestanden.

Kernprincipe: AI bepaalt WAT, deterministische code bepaalt HOE. Factuurnummers,
BTW-berekening, koersconversie en PDF-generatie lopen nooit "uit het hoofd" van de AI, maar
altijd via code. Zo blijft de administratie reproduceerbaar en controleerbaar.

Deze repo is een Claude Code plugin: hij levert alléén de skills + code. Jouw administratie
(facturen, bonnen, CSV's) blijft in je eigen map staan — die bezit je zelf, kun je backuppen,
en blijft staan als de plugin een update krijgt.

Wat kun je ermee?

In het slash-menu heten de skills vink:factuur, vink:bon, enz. (de plugin-naam is de
prefix). De korte vorm /factuur werkt ook gewoon — Claude herkent de bedoeling, ook midden in
een zin.

⚠️ Dit is een voorbereidend hulpmiddel. De skills berekenen en ordenen; de daadwerkelijke
aangiftes (BTW en inkomstenbelasting) dien je zelf in bij de Belastingdienst. Geen vervanging voor een
boekhouder of fiscaal advies — controleer de uitkomsten.

Vereisten

• Claude Code (CLI, desktop of VS Code-extensie).
• Node.js 18 of nieuwer (node --version). Géén npm-packages nodig.
• Google Chrome (of Chromium/Brave/Edge) voor het genereren van PDF's. Staat Chrome niet op de
  standaard macOS-locatie, zet dan de env-var ADMIN_CHROME:

  export ADMIN_CHROME="/Applications/Chromium.app/Contents/MacOS/Chromium"
  

• macOS. Vink is gebouwd en getest op de Mac. Op Linux en Windows werkt het rekenwerk, maar moet
  je ADMIN_CHROME zelf zetten en opent een PDF niet vanzelf (de skills gebruiken open).

Installeren (voor gebruikers)

Eenmalig, in Claude Code:

/plugin marketplace add mathijs-oord/vink-plugin
/plugin install vink@vink-plugin

Daarna:

1. Maak (of kies) een map voor je administratie, bv. ~/Administratie, en open die map in
   Claude Code (cd ~/Administratie en start Claude Code daar). Hier komt jouw data te staan.
2. Typ /setup-vink. Dat zet bij eerste gebruik de lege templates klaar in je map (data/-CSV's,
   business.example.json, een project-CLAUDE.md en de uitvoer-mappen) en vraagt vervolgens je
   bedrijfsgegevens (naam, adres, KvK, BTW-id, IBAN) + standaard betaaltermijn.
3. Probeer het uit, bijvoorbeeld:
   • /factuur → "Maak een factuur voor Acme B.V., 20 uur consultancy à €100."
   • /bon → "Verwerk deze bon" (+ pad naar een PDF/foto).
   • /aangifte → "Stel de aangifte voor dit kwartaal samen."

Werk je voor meerdere administraties? Maak per administratie een aparte map en draai /setup-vink in
elk. De plugin is overal beschikbaar; de data blijft per map gescheiden.

Updates ontvangen

Bij third-party marketplaces staat auto-update standaard uit. Twee opties:

• Handmatig (altijd de nieuwste versie ophalen):

  /plugin marketplace update vink-plugin
  

• Auto-update aanzetten: open /plugin → tabblad Marketplaces → kies
  vink-plugin → Enable auto-update. Updates komen dan bij het opstarten van Claude
  Code binnen.

Updates raken alleen de plugin-code/skills/regels — nooit je data. Je data/, facturen/,
bonnen/, aangiftes/ en jaaropgaven/ blijven onaangeroerd.

Hoe het is opgebouwd

De plugin (deze repo — wordt geüpdatet):

vink-plugin/
├── .claude-plugin/
│   ├── marketplace.json     marketplace-definitie (deze repo = marketplace)
│   └── plugin.json          plugin-manifest (naam: vink)
├── skills/                  de skills: setup, factuur, zelffactuur, bon, betaald, aangifte, dashboard, jaaropgave
├── lib/admin.mjs            deterministische kern (factuurnr, BTW, FX, PDF, CSV-I/O)
├── templates/               HTML-templates voor de factuur-, aangifte- en jaaropgave-PDF's + het dashboard
├── rules/                   Nederlandse BTW- en IB-regels in markdown — de kennisbron van de skills
└── seed/                    lege templates die /setup-vink naar je eigen map kopieert

Jouw map (per gebruiker — blijft van jou):

~/Administratie/
├── CLAUDE.md                projectconventies (door /setup-vink neergezet)
├── data/                    je administratie (CSV's + business.json)
├── facturen/<YYYY-QN>/      gegenereerde + geïmporteerde factuur-PDF's, per kwartaal
├── bonnen/<YYYY-QN>/        kopie van je bonbestanden, per kwartaal (bewaarplicht)
├── aangiftes/               de aangifte-PDF's per kwartaal
└── jaaropgaven/             de jaaropgave-PDF's per jaar

Je data & privacy

• Alles staat lokaal in je eigen map. Er gaat niets naar een externe administratie-dienst.
• De plugin-repo bevat nooit jouw administratie — alleen generieke code + lege templates.
• Twee externe aanroepen. Bij vreemde valuta haalt /bon de ECB-dagkoers op via de open
  frankfurter.app-API. En één keer per maand stuurt de plugin een
  anonieme ping naar vinkapp.nl, zodat de maker ziet hoeveel mensen Vink gebruiken: geen ID en
  niets uit je administratie, alleen of het de eerste keer is.
• De ping uitzetten: zet "telemetry": false in data/business.json, of gebruik de
  omgevingsvariabele VINK_TELEMETRY=0 of DO_NOT_TRACK=1.
• De volledige privacyverklaring: Privacy.

Veiligheid by design

De skills verwijderen of overschrijven nooit automatisch een factuur of bon. Corrigeren of
verwijderen doe je bewust met de hand in de CSV-bestanden. Zo kan een verkeerd begrepen opdracht
nooit stilletjes je administratie wissen.

Voor de maintainer (updates uitbrengen)

Deze repo is tegelijk de marketplace én de plugin (één-repo-opzet, plugin op de root via
"source": "./").

Een update uitbrengen = pushen naar de default branch:

git add -A
git commit -m "..."
git push

Het version-veld is bewust weggelaten uit plugin.json, dus elke commit telt als een nieuwe
versie. Gebruikers halen 'm op met /plugin marketplace update vink-plugin (of automatisch
als ze auto-update aan hebben). Wil je later vaste releases (semver), zet dan version in
plugin.json en hoog die per release op.

Lokaal testen vóór je pusht — in een aparte testmap, niet in deze repo:

/plugin marketplace add /pad/naar/deze/repo
/plugin install vink@vink-plugin

Daarna in een lege testmap /setup-vink draaien. Een marketplace op een lokaal pad laadt de plugin
rechtstreeks uit je werkmap: wijzigingen (ook ongecommitte) zijn actief na /reload-plugins of bij
een nieuwe sessie — committen of marketplace update is daarvoor niet nodig.

Validatie:

claude plugin validate .

Gebruikscijfers: lib/admin.mjs stuurt per administratie-map één anonieme ping per maand naar
/api/ping op vinkapp.nl (het telpunt staat in de vink-website-repo). De tellers lees je uit via
https://www.vinkapp.nl/api/stats?token=…. Zet bij het testen VINK_TELEMETRY=0 in je shell,
anders telt elke testmap mee als nieuwe gebruiker.

Architectuur kort: code/skills/regels/templates leven in de plugin en worden via
${CLAUDE_PLUGIN_ROOT} aangeroepen; data wordt door lib/admin.mjs weggeschreven relatief aan de
map waar Claude Code draait (process.cwd() / CLAUDE_PROJECT_DIR, te overriden met
ADMIN_DATA_DIR). Zo overleeft gebruikersdata elke plugin-update.

Herkomst

Afgeleid van de business-logica van Vink, een Mac-boekhoud-app waarvan de ontwikkeling is
gestopt. De fiscale rekenregels (BTW-routing, rubrieken, factuureisen) komen daaruit voort.

Gebruik op eigen verantwoordelijkheid; dit is geen fiscaal advies.