Velin-Meta (AI agents) 0.9.0

Machine-readable context for Cursor, Copilot, and custom agents — structured JSON, not hidden from humans.

1. What Velin-Meta is (and is not)

Velin-Meta is agent-optimized metadata: a compact snapshot of VelinStyle conventions, components, CLI, and doc links. It is not encryption, DRM, or “KI-only” access — any HTTP client can fetch velin-agent.json.

Goal: fewer hallucinated class names, correct doc URLs, aligned codegen.
Not a substitute: full docs, WCAG review, or security audits still need humans.

2. MIME and files

Artifact	Role
`dist/velin-agent.json`	Canonical bundle (components, CLI, conventions)
`dist/llms.txt`	Short index (llms.txt convention)
`application/vnd.velinstyle.meta+json`	MIME for page-level `<script id="velin-meta">`

Published on this site at /dist/velin-agent.json and /dist/llms.txt.

3. Live preview (this site)

Fetch the published bundle and inspect page-level meta embedded in this HTML — same artifacts agents use.

Global bundle summary

Open JSON llms.txt Feature scope

Loading…

Page meta on this page

From <script id="velin-meta">

npx velinstyle meta page my.html --write

4. Global bundle (`velinstyle meta`)

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

CI runs meta:build and fails if committed dist/velin-agent.json or dist/llms.txt drift from source.

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

Component inventory (0.9.0)

The bundle’s components object is derived from component-loaders.js (audit-harmonized):

components.tags — 36 canonical custom elements
components.loaderCount — 38 (includes deprecated velin-tooltip-wc, velin-stepper-wc)
components.legacyAliases — documents those aliases
components.helpers — velin-flip, velin-haptic, velin-reveal (JS modules, not custom elements)

Also includes attributes (27 built-in), cli, a11y, searchIndex, and documentation roots.

5. Page-level 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

Do not put secrets, API keys, or raw PII in page meta.

6. CLI workflows

velinstyle meta — rebuild bundle + llms.txt
velinstyle docs generate --scope meta — docs/generated/meta/README.md
velinstyle scaffold / blueprint — pair with agent rules that reference the bundle
velinstyle scan — validate generated HTML against framework rules

7. Cursor and other agents

Add to project rules or @-mention the bundle URL:

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.

8. Security

Meta files are public — treat them like README content.
No credentials, tokens, or personal data in JSON or llms.txt.
Agents still need your usual review for XSS, auth, and privacy.