Hoe de artefact-pipeline werkt: git als enige bron, het id als adres

Het principe in één alinea

Elk research-artefact van het lab is één zelfstandig HTML-bestand dat leeft in de git-repository RnD/helix-artifacts — git is de enige bron van waarheid. De app serveert een lokale spiegel van die repo en niets anders: wat niet in git staat, bestaat niet (en wordt bij de eerstvolgende synchronisatie ook fysiek opgeruimd). Het adres van een artefact is zijn onveranderlijke id: /artifacts/<art_id>/<leesbare-naam>.html. De naam erachter is cosmetiek; het id is wat notities, versies, koppelingen en gedeelde links bijeenhoudt. Sinds 2026-07-14 geldt dit voor alle artefacten: de 22 oude "baked" artefacten die nog in de app-image zaten zijn naar de repo gemigreerd, en elk oud pad stuurt bezoekers met een 301 door naar het id-adres.

Twee routes erin — allebei eindigen ze in git

Route A en B convergeren gegarandeerd: de spiegel wordt bij elke sync volledig vervangen door de repo-inhoud. Een bestand dat ooit buiten git om op de server zou belanden, overleeft de eerstvolgende sync dus niet — het systeem herstelt zichzelf altijd richting git. Dat maakt de pipeline deterministisch: dezelfde repo-stand geeft altijd dezelfde site-stand.

Waarom het id het adres is

Vroeger was het pad /artifacts/<spoor-map>/<naam>.html. Dat had twee problemen: de URL suggereerde spoor-lidmaatschap dat er niet hoefde te zijn, en elke hernoeming of verplaatsing brak alle gedeelde links. Nu:

• Het pad draagt het id — /artifacts/art_43af89353af0/dongemond-kandidaten-vergelijking.html. Spoor-koppeling is pure metadata (een docs-link op het spoor); "los" bestaat ook.
• Review-notities, versies en engagement-statistieken binden aan het id, niet aan de bestandsnaam — ze overleven elke hernoeming.
• Oude paden sterven nooit: elke verplaatsing laat een permanente 301 achter (artifact_redirects).
• /p/<art_id> is de permalink — hetzelfde geldt site-breed: /p/<prj_id> voor een spoor/halte en /p/<pst_id> voor een post. De deel-knoppen op de site delen die permalink. Hernoem je een halte, dan blijft óók de oude leesbare URL werken (slug-geschiedenis, 308).

Serveren, privacy en geschiedenis

• Serveren: publieke artefacten komen rechtstreeks uit de store-spiegel. Privé-artefacten (slotje in het dashboard, of een helix-artifact-private-meta-tag in het bestand zelf) zijn alléén zichtbaar na inloggen; anoniem krijgt een kale 404 — geen bevestiging dat er iets bestaat.
• Geschiedenis: elke upload of push is een commit met auteur en boodschap. Het 🕘-icoon in /admin/artifacts toont de volledige tijdlijn per artefact; oudere versies zijn per commit terug te lezen. Verwijderen (🗑, admin) is een delete-commit: het bestand verdwijnt van de site, maar de git-geschiedenis bewaart alles.
• Review: intern deel je de reader-URL (…/research/view?doc=…) — daar liggen de notities op tekstselecties, gebonden aan het artifact-id. De kale /artifacts/…-URL is voor extern delen en embeds.

Spelregels voor auteurs (en agents)

• Publiceer altijd via de pipeline: de upload-knop, POST /api/artifacts, of een commit in RnD/helix-artifacts. Nooit meer bestanden in static/artifacts van de app-repo zetten — die route is per 2026-07-14 afgesloten (alleen lib/ met huisstijl-assets blijft daar).
• Begin vanuit het huis-template (/artifacts/lib/TEMPLATE.html); ontbrekende huisstijl-includes worden bij upload automatisch geïnjecteerd, een bewust vrij-formaat artefact declareert helix-artifact-freeform.
• Laat het id met rust: nooit een bestaand art_…-id in een nieuw bestand kopiëren (dat voegt hun notities samen). Bijwerken van een bestaand artefact = uploaden met datzelfde id.
• Deel de permalink (/p/<id>) of het id-pad — nooit een zelfbedacht pad.