Folio
Lies die Anfrage und ein etwaiges bestehendes Artefakt, bevor du HTML schreibst. Jede externe Abhängigkeit und Veröffentlichungs-URL gehört in das Manifest-Ledger. Artefakte sind statische Dokumente – sie rufen keine APIs auf.
Wann Folio verwenden – und wann nicht
Folio ist für dauerhafte, öffnbare, teilbare Web-Deliverables – Dinge, die der Benutzer aufbewahrt, erneut öffnet oder an andere weitergibt.
Verwende Folio, wenn:
- Der Benutzer nach einem Dokument, Dashboard, Datenblatt, einer Foliensammlung oder einer Seite fragt, die er speichern oder versenden wird
- Die Ausgabe ein Deliverable ist, keine schnelle Ansicht („Erstelle mir einen Bericht“, „Baue ein Dashboard für das Team“, „Stelle das online“, „Ich möchte eine Seite, die …“)
- Der Benutzer explizit ein Verb aufruft (
folio publish,folio audit,folio remix,folio describe)
Verwende Folio nicht, wenn:
- Der Benutzer eine schnelle Ansicht, kein Deliverable wünscht („Zeig mir“, „Wie sieht das aus“, „Überprüfe nur“, „Kannst du anzeigen“)
- Die Ausgabe nach dieser Unterhaltung nicht wieder geöffnet wird – antworte inline oder schreibe eine Scratch-Datei, aber erstelle keinen Stempel, kein Ledger, kein Gate
- Die Anfrage nach einem Code-Snippet, einer Konfigurationsdatei oder einer einzelnen Funktion verlangt – das sind keine Browser-Artefakte
Eingangstor. Bevor du den Artefakt-Fluss beginnst, frage: Wird der Benutzer diese Datei nach dieser Sitzung wieder öffnen? Wenn nein, ist Folio das falsche Werkzeug – antworte einfach. Wenn ja, fahre fort.
Eigenständig ist der Standard. Der leichteste Folio-Pfad ist ein einzelner Ordner mit einer index.html – kein Site-Root, keine site.json, keine Index-Seite. Ein Site-Root erscheint nur, wenn ein zweites Artefakt vorhanden ist oder der Benutzer darum bittet, eine Sammlung zu veröffentlichen. Erstelle keine Site-Zeremonie für eine Datei.
Glossar
Verwende nur diese Begriffe in der Folio-Ausgabe.
| Begriff | Bedeutung |
|---|---|
| Artefakt | Ein eigenständiges statisches Web-Deliverable: HTML mit CSS/JS, ausführbar im Browser |
| Bundle | Eines von single-file (Inline-CSS/JS) oder multi-file (verlinkte Assets in einem Verzeichnis) |
| Artefakt-Typ | Einer von: doc, sheet, dashboard, explainer, slides, tool, landing |
| Host-Profil | Wo die Seite dauerhaft lebt: local, surge, gh-pages, cf-pages, cf-worker |
| Teilen (Tunnel) | Eine temporäre öffentliche URL zum laufenden lokalen Server, über localhost.run (Standard) oder ngrok. Flüchtig, die Maschine bleibt Host – keine Veröffentlichung |
| Site-Root | Ein Verzeichnis mit einer index.html und einer artifacts/-Baumstruktur, veröffentlicht als eine Domain. Artefakte sind Pfade darunter, keine separaten Subdomains. |
| Site-Manifest | .folio/site.json – die kanonische Quelle der Wahrheit. Trägt Domain + Pro-Artefakt-Register (Slug, Typ, Bundle, Ledger, Provenienz, Veröffentlichungsstatus). Stempel, Index und Audit leiten sich daraus ab. |
| Eigenständiges Artefakt | Ein Artefakt ohne Site-Root. Der HTML-Stempel ist sein einziges Manifest. Wird zu einem Site-Eintrag hochgestuft, wenn ein zweites Artefakt erscheint. |
| Provenienz | Das source-Feld eines remixten Artefakts: { slug, site, url }. Null für Originale. Wird von describe, audit und remix gelesen. |
| Manifest | Eintrag-HTML, Dateiliste, externe Abhängigkeiten und optionale Veröffentlichungsmetadaten |
| Ledger | Das Manifest-Ledger – Abhängigkeiten, Datendateien, URLs und Evidenzstufen vor dem Build |
| Gate | Eine binäre Prüfung, die vor der Übergabe bestanden werden muss |
| Evidenzstufe | Eine von observed, derived, stated, absent |
Wie man diese Fähigkeit nutzt
- Standard: Erstellen oder Aktualisieren eines Artefakts. Folge dem Artefakt-Fluss. Ein einzelnes Artefakt ist standardmäßig eigenständig – kein Site-Root erforderlich.
folio audit <pfad|url>: Schreibgeschütztes Audit. Keine Bearbeitung. Liesreferences/verbs/audit.md.folio describe <pfad|url|slug>: Lies den Manifest-Eintrag eines Artefakts (Typ, Ledger, Provenienz, Veröffentlichungsstatus). Liesreferences/verbs/describe.md.folio share <site-root>: Öffne einen temporären öffentlichen Link zur lokal laufenden Site über einen Tunnel (Standard localhost.run – keine Installation, kein Konto;--ngrokAlternative). Die Maschine bleibt der Host; die URL stirbt mit dem Prozess. Verwende dies für „Lass es jemanden jetzt sehen“, nicht zum Veröffentlichen. Liesreferences/verbs/share.md.folio publish <site-root>: Stelle einen Site-Root (alle Artefakte) auf dem gewählten Host-Profil für dauerhaftes Hosting bereit. Generiere zuerst den Index neu (scripts/gen-index.js), dann deploye. Liesreferences/verbs/publish.md.folio remix <pfad|url>: Forke ein Artefakt und ändere es, während die Manifest-Ehrlichkeit gewahrt und die Quell-Linie aufgezeichnet wird. Liesreferences/verbs/remix.md.
Ein Durchlauf = ein Artefakt, es sei denn, der Benutzer nennt mehrere. Bevorzuge das kleinste Bundle, das die Anfrage erfüllt. Ein einzelnes Artefakt ist eigenständig; mehrere Artefakte leben unter einem Site-Root und werden als eine Domain veröffentlicht. Lies references/site-index.md für das Site-Root-Modell und das Upgrade von eigenständig zu Site.
Nicht verhandelbare Disziplinen
- Lauffähig vor schön. Das Artefakt öffnet sich im Browser und Kerninteraktionen funktionieren vor der Verfeinerung oder Veröffentlichung.
- Nur statische Dokumente. Kein
fetch()zu externen APIs, keine WebSocket-Verbindungen, keinXMLHttpRequestzu Live-Endpunkten. Daten werden inline eingebettet, aus einer lokalen Datei perfetch('./data/…')geladen oder zur Build-Zeit generiert. Die einzigen Netzwerkanfragen, die ein Artefakt macht, sind an geledgerte CDN-Skripte, Styles und Schriftarten. - Manifest-Ehrlichkeit. CDN-Skripte, Schriftarten, Bilder und Datendateien sind Ledger-Zeilen, keine Überraschungen.
- Lokal zuerst, dann teilen, dann veröffentlichen. Standard-Host-Profil ist
local. Führe es dynamisch aus –node <folio-skill>/scripts/serve.js <site-root>stellt sicher, dass derartifacts/-Ordner vorhanden ist, generiert die Index-/Suchseite aus dem Ledger neu, sucht einen offenen Port und bedient über HTTP (einfachesfile://ist für eine vollständig inline eingebettete Einzeldatei in Ordnung, bricht aberfetchund Modul-Importe). Siehereferences/local-server.md. Um jemandem jetzt etwas zu zeigen, öffne einen temporären Tunnel –node <folio-skill>/scripts/share.js <site-root>(Standard localhost.run, keine Installation/Konto); der Link ist flüchtig und die Maschine bleibt der Host. Dauerhaftes Hosting woanders istpublish– nur, wenn der Benutzer darum bittet oderfolio publishaufgerufen wird. Gib niemals proaktiv Teilen- oder Veröffentlichungsfähigkeiten bekannt. - Keine Geheimnisse in statischen Dateien. API-Schlüssel, Tokens und private URLs gehören nicht in committetes oder veröffentlichtes HTML/JS.
- Nicht hässlich. Artefakte folgen der visuellen Baseline. Lies
references/visual-baseline.mdvor dem Build.
Gold-Entscheidungsablauf
Anfrage: Baue ein interaktives Latenz-Histogramm aus dieser CSV für einen Teamkollegen.
Inventar:
· Ziel: neues Artefakt `latency-hist`
· Vorhanden: keines
· Daten: Benutzer hat `runs.csv` angehängt (observed, 840 Zeilen)
· Einschränkungen: lokaler Ordner, keine Veröffentlichung
Auswahl: kind=explainer · bundle=multi-file · host=local · audience=teamkollege-übergabe
Ledger:
dep | kind | evidence | in artifact as
d3@7 (cdn.jsdelivr) | script | stated, benutzer hat nicht eingegrenzt | index.html script-tag + hinweis in README
runs.csv | data | observed | ./data/runs.csv, geladen über fetch('./data/runs.csv')
Dateiplan:
Erstellen: artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
Keine Löschungen.
Verifikation: npx serve artifacts/latency-hist; Diagramm rendert; Konsole sauber
Gates: opens-locally=ja, console-clean=ja, ledger-complete=ja, no-secrets=ja, mock-labeled=n/v, visual-baseline=ja
Übergabe: Pfad, wie zu öffnen, Ledger-Zusammenfassung, zurückgestellt: keines
Scope-Fork
Löse den Scope vor allgemeinen Designfragen.
| Anfrageform | Bundle | Host | Überspringen |
|---|---|---|---|
| Schnelle Wegwerf-Demo | single-file | local | README, veröffentlichen, mehrere Seiten |
| Geschriebenes Dokument oder Bericht | single-file oder multi-file | local | Diagramme, schweres JS |
| Datentabelle oder Datenblatt | single-file oder multi-file | local | Erzählender Prosa, Dekoration |
| Metrik-Dashboard | multi-file | local | Voll-CRUD, Live-Daten-Feeds |
| Konzept-Erklärung | multi-file | local | Dichte Rohdaten-Dumps |
| Foliensammlung | multi-file | local | Scroll-Layouts, Widgets |
| Geteiltes Team-Artefakt | multi-file | local | Framework-Build-Schritt |
| Jemandem jetzt zeigen | single-file oder multi-file | share (Tunnel) | Bereitstellungs-Zeremonie, dauerhafter Host |
| Dauerhafter öffentlicher Link | multi-file | surge oder cf-pages | Auth, Server-Logik |
| Agenten-Übergabe-Vorschau | single-file bevorzugt | local | Teilen/Veröffentlichen, es sei denn, angefragt |
Mehrdeutige Anfrage: einmal knapp nachfragen. Beispiel: „Einzelne eigenständige Datei oder kleiner Ordner mit separatem CSS/JS?“ Wenn unbeantwortet, wähle das kleinste Bundle, das funktioniert.
Artefakt-Fluss
0. Inventar
Lies die Anfrage und einen etwaigen bestehenden Artefakt-Baum. Lies references/evidence.md und references/artifact-types.md.
Sammle:
- Thema: Was das Artefakt zeigen oder den Benutzer tun lassen soll
- Eingaben: Dateien, JSON, CSV, Text, Design-Einschränkungen (mit Evidenzstufen)
- Vorhandenes Artefakt: Pfad, Eintrags-HTML, Manifest, letzte Veröffentlichungs-URL, falls vorhanden
- Host-Profil: Standard
local; liesreferences/host-profiles.md, wenn Veröffentlichung im Spiel ist - Konventionsquelle:
folio.md, falls vorhanden
Gib ein kompaktes Inventar mit Zitaten aus, bevor du fortfährst.
1. Auswahl
Gib vor dem Build aus: Auswahl: kind=<x> · bundle=<y> · host=<z> · audience=<a>.
Lies references/artifact-types.md, wenn der Typ unklar ist. Lies references/host-profiles.md, wenn der Host nicht local ist.
2. Manifest-Ledger
Baue das Ledger, bevor du HTML schreibst. Lies references/manifest-ledger.md.
Spalten:
dep | kind | evidence | in artifact as
Typen: script, style, font, image, data, mock, publish-target.
Datendateien und Mock-Daten müssen explizit sein. Externe API-Aufrufe sind außerhalb des Gültigkeitsbereichs – siehe Disziplin #2.
3. Dateiplan und Build
Gib den Dateiplan vor der Bearbeitung an:
Erstellen: artifacts/<slug>/index.html, app.js, data/sample.json
Ändern: keines
Keine Löschungen.
Beginne mit einer Vorlage. Lade references/templates/<kind>.html und passe sie an – ersetze die {{placeholder}}-Inhalte und <!-- Replace: ... -->-Marker durch echte Inhalte. Vorlagen sind selbst Gate-bestehende Folio-Artefakte; sie tragen den Token-Block, den Hell/Dunkel-Umschalter, das Favicon und die typspezifische Struktur. Lies das Verzeichnis references/templates/ für das, was jede Vorlage bietet.
Lies references/visual-baseline.md, bevor du CSS schreibst.
Baue mit einfachem HTML/CSS/JS, es sei denn, der Benutzer hat einen bestimmten Stack genannt. Bevorzuge:
- Semantisches HTML, eine offensichtliche Eintragsdatei (
index.html) - CSS-Custom-Properties für alle visuellen Tokens (Farbe, Typografie, Abstand, Radius, Schatten)
- OKLCH für Farbe; kein Inline-Hex/RGB außerhalb des
:root-Token-Blocks - Vanilla JS oder eine einzelne benannte CDN-Bibliothek – geledgert
multi-file: halte alle Asset-Pfade relativ; keine absoluten Maschinenpfade- Keine kursiven Überschriften; lesbare Maß (max-width: 60–70ch);
overflow-x: clipaufhtmlundbody
Lies references/security.md, wenn das Artefakt Benutzereingaben akzeptiert, Drittanbieter-Inhalte einbettet oder öffentlich veröffentlicht wird.
Stempel (HTML-Kommentar, oben in der Eintragsdatei):
<!-- Folio · slug: latency-hist · kind: explainer · bundle: multi-file · host: local -->
<!-- deps: d3@7 · data: runs.csv · publish: none -->
Für single-file halte den Stempel minimal (eine Zeile).
4. Verifikation
Lies references/verification.md. Führe Prüfungen durch, die zum Host-Profil passen.
Minimale Matrix:
check | command/evidence | result | notes
Beispiele: Statischer Server + Eintrags-URL laden, DevTools-Konsole sauber, primäre Interaktion durchklicken, defekte Links scannen, notiz zu file:// vs Server für fetch, visuelle Baseline-Stichprobe.
5. Gates
Wende vor der Übergabe an. Jedes nein löst eine Fehlerbehebungsschleife aus.
| Gate | Prüfung |
|---|---|
opens-locally | Eintrags-HTML lädt über statischen Server (oder ehrliches file://-Caveat dokumentiert); für Server-Setup siehe references/local-server.md (scripts/serve.js ist der Ein-Befehl-Pfad) |
console-clean | Keine ungehandelten Fehler auf primärem Pfad |
ledger-complete | Jede externe Abhängigkeit und Datenquelle erscheint im Ledger |
no-secrets | Keine Schlüssel, Tokens oder privaten URLs im Quellcode |
mock-labeled | Mock-/Beispieldaten beschriftet, wenn echte Daten fehlen |
static-only | Kein fetch() zu externen APIs, kein WebSocket, kein XHR zu Live-Endpunkten |
visual-baseline | Token-Block vorhanden, keine Inline-Farben außerhalb von :root, keine kursiven Überschriften, ausreichender Kontrast |
publish-ready | Bei Veröffentlichung: Host-Profil-Schritte dokumentiert und verifiziert oder explizit zurückgestellt |
manifest-derivation | Hinweis. HTML-Stempel (Slug, Typ, Bundle) stimmt mit dem site.json-Eintrag für dieses Artefakt überein. Zeigt Abweichungen an; siehe references/verification.md#manifest-derivation-check. |
Lies references/slop-test.md nach dem Build. Behebe P0/P1 vor der Übergabe.
6. Veröffentlichen (optional)
Nur, wenn der Benutzer die Veröffentlichung anfordert oder folio publish aufruft. Lies references/verbs/publish.md und die tiefgehende Datei des Host-Profils.
Notiere die Veröffentlichungs-URL im Manifest und bei der Übergabe. Belege niemals eine URL ohne Evidenz aus der Ausgabe des Veröffentlichungsbefehls.
7. Übergabe
Enthalte:
- Artefakt-Pfad und Eintragsdatei
- Wie man lokal öffnet (genauer Befehl)
- Veröffentlichungs-URL (falls veröffentlicht), mit Evidenz
- Zusammenfassung des Manifest-Ledgers
- Verifikationsbefehle und -ergebnisse
- Zurückgestellte Punkte (z. B.
fetcherfordert Server, Mock-Daten in Verwendung)
Vergrabe keine Manifest- oder Veröffentlichungsfakten unter Implementierungs-Geschwätz.
BAD/GOOD-Kontraste
SCHLECHT: fetch('/api/users') einbauen, weil Dashboards normalerweise Benutzer von einer API laden.
GUT: data/users.json mit einem sichtbaren „Beispieldaten“-Label einbetten. Keine API-Aufrufe.
SCHLECHT: Google Analytics, Schriftarten und drei CDN-Bibliotheken einfügen, ohne sie aufzulisten. GUT: Jede Abhängigkeit ist eine Ledger-Zeile mit URL und Zweck.
SCHLECHT: „Bereitgestellt unter https://demo.example.com“ mit keinem ausgeführten Veröffentlichungsbefehl. GUT: Veröffentlichungs-URL aus der Befehlsausgabe kopiert oder als zurückgestellt markiert.
SCHLECHT: Inline oklch()-Werte verstreut über das CSS, drei verschiedene font-family-Deklarationen.
GUT: Alle visuellen Werte im :root-Token-Block, referenziert über var().
Konventions-Artefakte
folio.md (Ausgabeverzeichnis, Standard-Host, CDN-Zulassungsliste, Benennung): Opt-in. Lies references/folio-md.md. Sobald vorhanden, gewinnen die Haus-Standards.
Optionales, projektspezifisches Layout: