// ── Werkwijze: stappenplan voor AI-agenten die via de MCP-server een dossier
// behandelen ───────────────────────────────────────────────────────────────
// Machineleesbaar antwoord op "hoe gebruik ik deze tools om, op basis van
// aangeleverde brondocumenten, tot een volledig werkdossier te komen?". Elke
// stap verwijst naar de bijbehorende operationId's, zodat een agent de juiste
// volgorde en samenhang kent zonder te moeten gokken.
//
// DEKKINGSREGEL (bewaakt door lib/mcp/werkwijze-dekking.test.ts): élke tool
// van de MCP-server komt in minstens één stap voor — een nieuwe endpoint in
// lib/openapi.ts zonder plaats in dit stappenplan laat de test falen. Zo kan
// een agent die enkel haalWerkwijze leest, gegarandeerd álle operationele
// mogelijkheden van de server ontdekken.

export interface WerkwijzeStap {
  stap: number;
  titel: string;
  omschrijving: string;
  tools: string[];
}

export const WERKWIJZE = {
  doel:
    "Stappenplan voor een AI-agent die, op basis van door de notaris " +
    "aangeleverde (geanonimiseerde) brondocumenten, een volledig werkdossier " +
    "samenstelt: ontwerpdocument, modelmail(s), afrekening(en) en " +
    "termijnbewaking. Het resultaat is steeds een werkdocument — de notaris " +
    "leest na en valideert vóór gebruik.",
  uitgangspunten: [
    "Lees en begrijp de brondocumenten zelf (buiten Notary.AI): bepaal het " +
      "aktetype, de partijen, de relevante feiten en bedragen. Notary.AI " +
      "bevat geen documentherkenning — dat is de taak van de agent.",
    "Werk met geanonimiseerde gegevens: vervang namen/adressen/bedragen door " +
      "neutrale placeholders zodra je ze naar Notary.AI stuurt, en herstel de " +
      "echte gegevens pas lokaal in het eindresultaat voor de gebruiker. " +
      "Uitzondering met omgekeerde flow: het intake-JSON voor de lokale " +
      "dossierimport (stap 8) bevat wél persoonsgegevens en blijft daarom " +
      "volledig LOKAAL — het gaat nooit naar een Notary.AI-endpoint.",
    "Volg de stappen hieronder niet star: sla stappen over die niet relevant " +
      "zijn voor het dossier (bv. geen schenkbelasting bij een zuivere " +
      "verkoop), en herhaal stappen voor meerdere partijen/brieven.",
    "Binnen GENEREREN/BEREKENEN/OPZOEKEN (stappen 0-8) mag je volledig vrij " +
      "en proactief werken. Wil je de gedeelde bibliotheek of kantoorkennis " +
      "uitbreiden of verbeteren (stappen 9-10), dan loopt dat altijd via een " +
      "voorstel dat de notaris valideert.",
    "Voor stap 1 kan bepaalAkteType het akteType voorstellen op basis van " +
      "uitsluitend het dossiertype en (bij verkoop) of er al een " +
      "compromisdatum gekend is — geen namen, adressen of bedragen, dus " +
      "altijd veilig om rechtstreeks aan te roepen. Het antwoord geeft ook " +
      "aan of er al een passend modeldocument bestaat ('modelGevonden'), " +
      "zodat je weet of je meteen naar stap 3 (haalModeldocument) kan of " +
      "eerst een wijzigingsvoorstel nodig is (stap 9).",
    "Op dezelfde manier geeft bepaalModelmailCategorieen — eveneens op basis " +
      "van enkel het dossiertype — de relevante modelmail-categorieën met de " +
      "beschikbare modelbrieven, zodat je snel het juiste hoofdstuk kiest " +
      "voordat je een modelmail invult (haalModelbrief).",
  ],
  stappen: [
    {
      stap: 0,
      titel: "Oriënteer je: werkwijze, kantoorkennis en checklists",
      omschrijving:
        "Roep bij twijfel over volgorde of samenhang eerst haalWerkwijze op " +
        "(dit stappenplan). Raadpleeg daarnaast, vóór je aan een dossier " +
        "begint: lijstKennisbank voor de door de notaris gevalideerde " +
        "kantoorkennis (werkwijzen, juridische aandachtspunten, " +
        "kantoorgebruiken — doorzoekbaar op thema) en haalAkteChecklists voor " +
        "de gewogen controlelijst van de rechtshandeling (cruciaal/belangrijk/" +
        "nuttig/overbodig, inclusief de track-changes-werkwijze om teksten " +
        "van derden — makelaar, bank, confrater — aan te passen). Pas die " +
        "kennis en checklists actief toe in alle volgende stappen.",
      tools: ["haalWerkwijze", "lijstKennisbank", "haalAkteChecklists"],
    },
    {
      stap: 1,
      titel: "Kies het juiste modeldocument en/of de juiste modelbrief(en)",
      omschrijving:
        "Raadpleeg lijstModeldocumenten en/of lijstModelbrieven en filter op " +
        "akteType/categorie en thema om het model te vinden dat bij het " +
        "dossier past; gebruik desgewenst bepaalAkteType om het akteType " +
        "zelf te laten voorstellen en bepaalModelmailCategorieen om de " +
        "relevante mail-hoofdstukken per dossiertype te kennen. Bestaat er " +
        "geen passend model, ga dan verder met de best passende basis en " +
        "markeer afwijkingen, of dien achteraf een wijzigingsvoorstel in " +
        "(stap 9).",
      tools: ["lijstModeldocumenten", "lijstModelbrieven", "bepaalAkteType", "bepaalModelmailCategorieen"],
    },
    {
      stap: 2,
      titel: "Controleer eerst de verplichte vastgoedopzoekingen",
      omschrijving:
        "Doe dit vóór je het document invult of de afrekening maakt: raadpleeg " +
        "haalOpzoekingen voor de rechtshandeling en het gewest om na te gaan " +
        "welke attesten/opzoekingen verplicht of gangbaar zijn. Het resultaat " +
        "stuurt de twee volgende stappen: (a) een verplichting of een " +
        "opzoekingsresultaat kan een facultatief onderdeel of een hypothese in " +
        "het ontwerpdocument relevant maken (bv. een syndicus-clausule bij een " +
        "appartement, een bodemverontreinigingsclausule bij een positief " +
        "bodemattest), en (b) elke opzoeking die het kantoor effectief " +
        "aanvraagt, is een leveringskost die in de afrekening moet verschijnen " +
        "(zie stap 5, extraLeveringskosten).",
      tools: ["haalOpzoekingen"],
    },
    {
      stap: 3,
      titel: "Verken structuur en parameters vóór het invullen",
      omschrijving:
        "Roep haalModeldocument / haalModelbrief op zonder invulwaarden om de " +
        "volledige structuur, de hypotheses (varianten) en de lijst " +
        "{{parameters}} te zien. Elke parameter komt met een invulhulp: " +
        "omschrijving (wat er precies moet komen), een realistisch voorbeeld " +
        "(formaat/stijl) en een herkomst — lees die vóór het invullen en volg " +
        "het voorbeeldformaat. Bij herkomst 'afgeleid' is er geen declaratie: " +
        "leid de betekenis af uit de clausuletekst rond de placeholder en laat " +
        "de parameter bij twijfel leeg ([AAN TE VULLEN]) — nooit gokken. " +
        "Bepaal, mede op basis van de brondocumenten " +
        "én het opzoekingenresultaat uit stap 2, welke facultatieve onderdelen " +
        "en welke hypotheses van toepassing zijn.",
      tools: ["haalModeldocument", "haalModelbrief"],
    },
    {
      stap: 4,
      titel: "Genereer het ingevulde ontwerpdocument en de modelmail(s)",
      omschrijving:
        "Roep haalModeldocument opnieuw op, nu met één queryparameter per " +
        "{{parameter}} en facultatief=... voor de relevante facultatieve " +
        "onderdelen (incl. die uit stap 2); doe hetzelfde voor haalModelbrief " +
        "met varianten=... voor de relevante hypotheses. Of laat de " +
        "hypothesekeuzes DETERMINISTISCH maken: geef aan " +
        "genereerOntwerpUitKenmerken (en aan genereerWerkdossierAlsWord, stap " +
        "7) álle kenmerken mee die je met zekerheid uit de stukken kent — " +
        "goedType, metKrediet, epcAanwezig, asbestAanwezig, syndicusInfo, " +
        "fiscaalRegime, ... (volledige lijst met effect: de 'handleiding' in " +
        "het antwoord). Elk aangeleverd feit kiest automatisch de juiste " +
        "hypothese; laat een feit weg als je twijfelt — nooit gokken. Het " +
        "resultaat is een werkdocument: niet-ingevulde parameters blijven " +
        "[AAN TE VULLEN: …] en hypotheses blijven gemarkeerd ter keuze tot de " +
        "notaris ze bevestigt.",
      tools: ["haalModeldocument", "haalModelbrief", "genereerOntwerpUitKenmerken"],
    },
    {
      stap: 5,
      titel: "Bereken de afrekening — inclusief effectief gemaakte opzoekingskosten",
      omschrijving:
        "Bereken op basis van de feiten uit de brondocumenten de indicatieve " +
        "aktekosten/ereloon (berekenAktekosten) en, indien van toepassing, de " +
        "schenk- of erfbelasting (berekenBelasting). Geef bij berekenAktekosten " +
        "via extraLeveringskosten=... de id's mee van elke niet-standaard " +
        "leveringskost (zie 'levKosten' in het antwoord) waarvan de opzoeking " +
        "uit stap 2 effectief werd aangevraagd, zodat die kost mee in het " +
        "totaal wordt opgenomen. Beide endpoints leveren een indicatief (BETA) " +
        "resultaat dat de notaris valideert.",
      tools: ["berekenAktekosten", "berekenBelasting"],
    },
    {
      stap: 6,
      titel: "Bewaak de termijnen van het dossier",
      omschrijving:
        "Bereken bij elk verkoopdossier met een gekende compromisdatum de " +
        "lopende termijnen via berekenDossierTermijnen (structureel: enkel de " +
        "compromisdatum, de overeengekomen krediettermijn in weken en of het " +
        "krediet al aanvaard is — geen namen of bedragen): de vervaldag van de " +
        "opschortende voorwaarde van financiering en de uiterste datum van de " +
        "authentieke akte (vier maanden standaard; geef een afwijkende " +
        "contractuele termijn mee via aktetermijnMaanden of " +
        "aktetermijnUiterlijkeDatum). Gebruik het urgentieniveau " +
        "('verstreken'/'nabij'/'ok') om de notaris proactief te waarschuwen, " +
        "de ondertekening tijdig te plannen en de juiste vervolgstap of " +
        "rappelmail te kiezen. Vraag daarnaast na elke statuswijziging via " +
        "bepaalVolgendeStappen (structureel: dossiertype + status + optionele " +
        "vlaggen appartement/kredietAanvaard) de concrete acties en " +
        "modelmail-categorieën van de huidige dossierfase op.",
      tools: ["berekenDossierTermijnen", "bepaalVolgendeStappen"],
    },
    {
      stap: 7,
      titel: "Lever het resultaat als Word-bestand(en) aan de gebruiker",
      omschrijving:
        "Bundel het volledige werkdossier met genereerWerkdossierAlsWord " +
        "(modeldocumentId, modeldocumentParametersJson idem stap 4, de " +
        "deterministische kenmerken die je zeker weet, modelbrievenJson als " +
        "JSON-array van {id, parameters, varianten}, en de " +
        "afrekeningsparameters uit stap 5). Wil de gebruiker enkel het losse " +
        "ontwerpdocument, gebruik dan haalModeldocumentAlsWord (zelfde " +
        "parameters als haalModeldocument, plus taal/gewest/notities). Beide " +
        "geven base64 én een downloadUrl (24 uur geldig, opent het bestand via " +
        "haalGegenereerdBestand): decodeer base64 lokaal, of deel de " +
        "downloadUrl als klikbare Markdown-link (bv. [bestandsnaam](downloadUrl)), " +
        "nooit als kale URL. Geef het bestand ongewijzigd door. " +
        "ELKE generatie bewaart bovendien haar volledige invoer 24 uur als " +
        "bijwerkbare sessie onder het 'dossierToken' in het antwoord — bewaar " +
        "dat token: komen er nadien stukken bij (een attest, een gecorrigeerd " +
        "bedrag, een extra clausule), lever dan enkel de aanvulling aan via " +
        "werkWerkdossierSessieBij en het .docx wordt geregenereerd zonder dat " +
        "je de rest opnieuw moet opgeven. Raadpleeg de bewaarde invoer met " +
        "haalWerkdossierSessie en het overzicht met lijstWerkdossierSessies " +
        "(voor de gebruiker: /werkdossiers in de app).",
      tools: [
        "genereerWerkdossierAlsWord",
        "haalModeldocumentAlsWord",
        "haalGegenereerdBestand",
        "lijstWerkdossierSessies",
        "haalWerkdossierSessie",
        "werkWerkdossierSessieBij",
      ],
    },
    {
      stap: 8,
      titel: "Wil de gebruiker het dossier in de app? Maak lokaal het intake-JSON",
      omschrijving:
        "Wanneer de gebruiker het dossier in de module Dossiers wil opvolgen " +
        "(bron-getrackte velden, ontbrekende stukken, termijnbewaking in de " +
        "app), haal dan de extractie-instructies op via haalIntakeInstructies " +
        "en zet het brondocument LOKAAL om naar het intake-JSON " +
        "(notary-ai-dossier-intake). LET OP de omgekeerde privacy-flow: dat " +
        "JSON bevat wél persoonsgegevens en blijft tussen jou en de notaris — " +
        "het gaat nooit naar een Notary.AI-endpoint; de notaris plakt het " +
        "zelf in /dossier → 'Importeer uit brondocument'.",
      tools: ["haalIntakeInstructies"],
    },
    {
      stap: 9,
      titel: "Mist de bibliotheek iets? Dien een wijzigingsvoorstel in",
      omschrijving:
        "Enkel wanneer een nodig modelonderdeel, modeldocument of modelbrief " +
        "nog niet bestaat of moet worden bijgewerkt: raadpleeg eerst " +
        "haalModelonderdeelRichtlijnen / haalModeldocumentRichtlijnen en dien " +
        "daarna voegModelonderdeelVoorstelToe / voegModeldocumentVoorstelToe " +
        "in. Controleer met lijstModelonderdeelVoorstellen / " +
        "lijstModeldocumentVoorstellen wat er al is ingediend, zodat je geen " +
        "dubbel voorstel doet. Dit wijzigt de gedeelde bibliotheek nooit " +
        "rechtstreeks — het voorstel komt in het tabblad 'Te valideren' en de " +
        "notaris keurt goed.",
      tools: [
        "haalModelonderdeelRichtlijnen",
        "haalModeldocumentRichtlijnen",
        "voegModelonderdeelVoorstelToe",
        "voegModeldocumentVoorstelToe",
        "lijstModelonderdeelVoorstellen",
        "lijstModeldocumentVoorstellen",
      ],
    },
    {
      stap: 10,
      titel: "Sluit de kwaliteitslus: signalen, verbeterpunten en nieuwe kantoorkennis",
      omschrijving:
        "Na (of tijdens) het dossierwerk: raadpleeg liever bepaalVerbeterkandidaten dan " +
        "lijstGebruikslog rechtstreeks — die tool clustert de gebruikslog én de " +
        "bibliotheek-audit al tot gerangschikte kandidaten (frequentie × ernst × " +
        "recentheid), elk gerouteerd naar zijn kanaal ('bibliotheek' → stap 9, " +
        "'code' → een verbetervoorstel, 'kennis' → voegKennisVoorstelToe). " +
        "Raadpleeg lijstVerbetervoorstellen voor de openstaande verbeterpunten die de " +
        "notaris zelf heeft ingediend (met prioriteit en acceptatiecriteria). " +
        "Heb je in het dossier generieke kantoorkennis opgedaan (een werkwijze, " +
        "een juridisch aandachtspunt, een kantoorgebruik — nooit " +
        "persoonsgegevens), dien ze dan in via voegKennisVoorstelToe; het item " +
        "krijgt status 'te valideren' en de notaris keurt het goed in de " +
        "module Kennisbank.",
      tools: ["bepaalVerbeterkandidaten", "lijstGebruikslog", "lijstVerbetervoorstellen", "voegKennisVoorstelToe"],
    },
  ] satisfies WerkwijzeStap[],
};