Artefact-templates & schrijfregels

Kies je template — en splits op doel

• Onderzoek (data, figuren, conclusies) → paper-template: abstract met kernresultaten, genummerde secties, figuren mét bijschrift, bronnenlijst met vintage, verantwoording.
• Procedure of uitleg (runbook, how-to, explainer zoals deze) → runbook-template: doel + geldt-voor, voorwaarden, stappen met verwachte uitvoer, verificatie, "als het misgaat", eigenaar + laatst-getest-datum. Nooit secrets in het bestand.

Eén artifact = één doel. Eén onderzoeksvraag, één procedure of één uitleg per bestand. Mengt een document doelen (onderzoek + handleiding)? Splits het en verwijs over en weer — kleine, doelgerichte artifacts blijven vindbaar, reviewbaar en hervalideerbaar.

Gereedschap-huisstandaard

• Kleine/middelgrote datasets → SQLite (huisstandaard in de hele stack); analytisch werk op bestanden mag ook met DuckDB. De data reist mee als sidecar-.js naast het artifact of inline — altijd mét het bronpad of de query waarmee ze zijn opgehaald.
• Live waterschapsdata → de MCP-servers (zinfo, omgeving, pdok, rws, bro, legger, omgevingswet). Vermeld server + tool + ophaaldatum als bron — live data zonder peildatum is niet reproduceerbaar.
• Interactieve grafieken → Plotly (2D én 3D) met het huisthema: /artifacts/lib/plotly.min.js + /artifacts/lib/helix-plotly.js (HXP.layout/HXP.config). Nooit een externe CDN — alles self-hosted.
• Formules → native MathML in een .formule-blok mét symbolentabel: elk symbool krijgt betekenis, eenheid en herkomst. Geen KaTeX/MathJax nodig — alle grote browsers renderen MathML Core sinds 2023. Een formule zonder uitgelegde symbolen is niet traceerbaar.

Wat de pipeline zelf bewaakt

Bij elke upload injecteert de server ontbrekende huisstijl-assets en het duurzame id, en toetst hij zachte kwaliteitshints — ontbrekende bronnen of verantwoording, placeholder-datums, figuren zonder bijschrift, formules zonder symbolentabel, een runbook zonder rollback-sectie. Hints blokkeren nooit; je ziet ze na de upload in Beheer → Artefacten en als hints-veld in de API-response. Templates declareren hun soort met <meta name="helix-artifact-template" content="paper|runbook">; confidentieel werk markeert zichzelf privé met <meta name="helix-artifact-private" content="true">.

Verder lezen

• Hoe de artefact-pipeline werkt — git als enige bron, het id als adres, privacy en versies.
• Reviewworkflow — hoe een artefact van concept naar definitief komt (apart artifact, intern).