Velin-Meta (KI-Agenten) 1.2.0 beta

Maschinenlesbarer Kontext für Cursor, Copilot und eigene Agenten — strukturiertes JSON, nicht vor Menschen verborgen. English: Velin-Meta · AI Skills Leitfaden

Reifegrad: Diese Oberfläche ist in VelinStyle 1.2.0 beta / foundation — jetzt nutzbar; Schemas und Abdeckung wachsen noch. CSS / Web Components / Runtime bleiben stable. Studio und die komplette Utility Engine bleiben planned.

Wann sinnvoll

Diesen Leitfaden nutzen, wenn Velin-Meta integriert oder erweitert wird (Velin-Meta 1.2.0 beta).
@birdapi/velinstyle@1.2.0 pinnen und Reifegrad-Badges für Beta-Oberflächen beachten.

Wann nicht

Plan / Review / Meta nicht als fertiges KI-Designsystem behandeln.
Keine Studio- oder Utility-Engine-APIs erfinden, die noch planned sind.

1. Was Velin-Meta ist (und nicht ist)

Velin-Meta ist agentenoptimierte Metadaten: ein kompakter Snapshot von VelinStyle-Konventionen, Komponenten, CLI und Doc-Links. Es ist kein Verschlüsselung, DRM oder „nur für KI“ — jeder HTTP-Client kann velin-agent.json abrufen.

Ziel: weniger halluzinierte Klassennamen, korrekte Doc-URLs, ausgerichtetes Codegen.
Kein Ersatz: vollständige Docs, WCAG-Review oder Security-Audits brauchen weiterhin Menschen.

2. MIME und Dateien

Artefakt	Rolle
`dist/velin-agent.json`	Kanonisches Bundle (Komponenten, Knowledge Graph, Pages, Sections, CLI, Konventionen)
`dist/llms.txt`	Agent-Briefing + Index (llms.txt-Konvention)
`application/vnd.velinstyle.meta+json`	MIME für seitenweises `<script id="velin-meta">`

Auf dieser Site unter /dist/velin-agent.json und /dist/llms.txt veröffentlicht.

3. Live-Vorschau (diese Site)

Das veröffentlichte Bundle abrufen und seitenweises Meta in diesem HTML prüfen — dieselben Artefakte, die Agenten nutzen.

Globales Bundle (Kurzüberblick)

JSON öffnen llms.txt Feature scope

Laden…

Seiten-Meta auf dieser Seite

Aus <script id="velin-meta">

npx velinstyle meta page my.html --write

4. Globales Bundle (`velinstyle meta`)

npx velinstyle meta
npx velinstyle meta --base-url https://velinstyle.info
npm run meta:build

CI führt meta:build aus und schlägt fehl, wenn committed dist/velin-agent.json oder dist/llms.txt von der Quelle abweichen.

Programmatisch: import { buildAgentBundle } from '@birdapi/velinstyle/meta'.

Komponenten-Inventar (1.2.0)

Das components-Objekt im Bundle stammt aus component-loaders.js (audit-harmonisiert):

components.tags — 40 kanonische Custom Elements
components.loaderCount — 40 (inkl. deprecated velin-tooltip-wc, velin-stepper-wc)
components.legacyAliases — dokumentiert diese Aliase
components.helpers — velin-flip, velin-haptic, velin-reveal (JS-Module, keine Custom Elements)

Enthält außerdem attributes (27 built-in), cli, a11y, searchIndex und documentation-Roots.

5. Seitenweises Meta

<script type="application/vnd.velinstyle.meta+json" id="velin-meta">
{
  "page": { "intent": "component-doc", "source": "docs/components/buttons.html" },
  "allowed": { "classesPrefix": ["velin-"], "components": ["velin-modal"] }
}
</script>

npx velinstyle meta page my-page.html --write

Keine Secrets, API-Keys oder rohe PII in Seiten-Meta ablegen.

6. CLI-Workflows

velinstyle meta — Bundle + llms.txt neu bauen
velinstyle docs generate --scope meta — docs/generated/meta/README.md
velinstyle scaffold / blueprint — mit Agent-Regeln kombinieren, die das Bundle referenzieren
velinstyle scan — generiertes HTML gegen Framework-Regeln prüfen

7. Cursor und andere Agenten

In Projektregeln ergänzen oder Bundle-URL @-erwähnen:

When editing VelinStyle HTML:
- Use only velin-* classes and documented velin-* Web Components.
- Follow dist/velin-agent.json conventions.
- Run velinstyle scan on new markup.
- Resolve doc links from /docs/ root, not the current folder.

Verwandt: Prompt-Vorlagen, API-Referenz (generiert).

8. Sicherheit

Meta-Dateien sind öffentlich — wie README-Inhalt behandeln.
Keine Credentials, Tokens oder personenbezogene Daten in JSON oder llms.txt.
Agenten ersetzen nicht die übliche Prüfung zu XSS, Auth und Datenschutz.