AGENTS.md

VelarScript Libraries Agent Guide

This repository owns officially maintained, optional VelarScript libraries and adapters. It does not own the language, Standard API, official target frameworks, or velar lsp server.

• Every public package lives under packages/*, is independently versioned, and must remain installable from the public @velarscript-labs npm scope without a checkout of VelarScript Core. The @velarscript/* scope is reserved for the language toolchain and official Standard/target owners.
• Never introduce a velar/* alias, compiler privilege, hidden CLI asset, repository-relative Core import, or synchronized toolchain release version.
• A Vel-authored package declares velar.entry, velar.artifacts, velar.targets, and velar.requires.capabilities; it publishes readable source plus the generated ABI-1 JavaScript, source map, portable interface, and receipt, and its root npm export points at that JavaScript. Regenerate the artifact with velar build-library after every source or version change. A JavaScript/TypeScript tooling package uses ordinary npm exports and must not duplicate compiler semantics.
• Keep external bridges narrow and checked. Validate untrusted results before they leave the adapter and document applicable memory, result, queue, concurrency, cancellation, and cleanup bounds.
• @velarscript-labs/editor-kit owns only editor connection metadata and helpers. Grammar, types, diagnostics, formatting, completion, and Web semantics stay in the installed VelarScript toolchain reached through standard LSP.
• @velarscript-labs/contract-codegen writes .vel source and hands it to the consuming project's own velar format. It owns no grammar, no type rules, and no transport protocol; a shape outside its closed mapping table fails closed with the schema path named rather than being guessed.
• Resolve every advisory printed by velar check: change the spelling or add one applicable // velar-allow <CODE>: <reason> suppression.
• Run the narrow package checks first, then npm run validate. Validation must exercise packed tarballs in an isolated consumer before a package is ready for release.
• A package whose boundary is a browser capability owns a runnable application under examples/, driven by that package's own test:browser script in Chromium and WebKit, and reached from the repository by npm run test:browser. The example lives beside packages/ rather than inside the package because a Core project's velar check walks its whole directory tree for test roots and does not stop at a nested velar.json.
• Preserve unrelated work. Commit, push, tag, npm publication, removal, and deprecation are separate authorization boundaries.