@velarscript/cli 0.19.1 → 0.20.1

package/skill/ai-skill-node.md

@@ -10,11 +10,12 @@ capabilities, or application configuration.
 path-pattern strings, Node modules, HTTP/WebSocket transport, and low-level
 server lifecycle; it does not own convention-based application configuration.
 An ordinary service activates `@velarscript/server` and then loads
-`velar skill server` for root `application.*`, application assembly, and
+`velar skill server` for manifest-declared application configuration, assembly, and
 connection lifecycle.
 
-A deliberately low-level Node application may activate Node directly and name
-one exported zero-argument async startup function:
+A deliberately low-level Node application may activate Node directly. Its
+selected entry source owns startup inside `@main`, exactly like Core, Web, and
+Desktop entries:
 
 ```json
 {
@@ -23,42 +24,41 @@ one exported zero-argument async startup function:
   "outDir": "dist",
   "publicDir": "public",
   "build": {"mode": "production", "sourceMaps": false},
-  "extensions": ["@velarscript/node"],
-  "node": {
-    "app": "start"
-  }
+  "extensions": ["@velarscript/node"]
 }
 ```
 
 The low-level entry owns its own startup arguments in code:
 
 ```velar fragment
-import {serve} from "velar/serve"
+import {run, serve} from "velar/serve"
 import {app} from "./app.vel"
 
-export async def start():
-    return await serve(app, port=3000, host="127.0.0.1")
+@main:
+    const server = await serve(app, port=3000, host="127.0.0.1")
+    await run(server)
 ```
 
-For one shared HTTP/WebSocket application port, the same exact zero-argument
-shape returns `Promise<WebSocketServer>`:
+For one shared HTTP/WebSocket application port, use the WebSocket transport's
+matching lifecycle operation:
 
 ```velar fragment
 import {app as routes} from "./app.vel"
-import {listen} from "velar/websocket"
+import {listen, run} from "velar/websocket"
 
-export async def start():
-    return await listen({
+@main:
+    const server = await listen({
         host: "127.0.0.1",
         port: 3000,
         http: routes,
         origins: ["https://app.example.com"],
         maxBodyBytes: 16777216,
     })
+    await run(server)
 ```
 
-The exact result is `Promise<WebSocketServer>`. The launcher supplies no
-host, port, or body-limit parameters.
+`run(server)` owns SIGINT/SIGTERM shutdown for either transport. The external
+CLI executes the compiled entry module directly.
 
 Use direct Node activation for tools, embedded adapters, and tests. For an
 application service, activate `@velarscript/server`; it provides the same
@@ -83,14 +83,14 @@ type CreateArticle:
 
 export server articles:
     /// Reports whether this service is ready.
-    @get(p"/health") => {ok: true}
+    @get health(p"/health") => {ok: true}
 
-    @get(p"/articles/{id:number}?{details:bool?}"):
+    @get readArticle(p"/articles/{id:number}?{details:bool?}"):
         if id < 1:
             throw HttpProblem({status: 404, code: "article.not_found", title: "Article not found"})
         return {id, details: details ?? false}
 
-    @post(p"/articles", input: CreateArticle):
+    @post createArticle(p"/articles", input: CreateArticle):
         return created({id: 1, title: input.title})
 
 ```
@@ -114,6 +114,12 @@ patterns require `as name` so the compiler never injects identifiers that are
 hidden inside another declaration. The old `path=` spelling is an error with a
 mechanical fix to the positional form and `as path`.
 
+For a public contract, put one stable source identifier between the role and
+the pattern: `@get readArticle(...)` or `@websocket worldRealtime(...)`.
+Operation identities must be unique after composition, survive `prefix`, and
+are emitted verbatim to OpenAPI. Leave the name out only for a local route whose
+method/path-derived OpenAPI identity is sufficient.
+
 On `POST`, `PUT`, or `PATCH`, one concrete Data parameter is the
 checked JSON body. A `Request` parameter explicitly requests the complete
 request, including `queryAll` and cooperative `cancellation`. Ambiguous bodies,
@@ -218,6 +224,12 @@ An app-scoped provider may depend only on other app-scoped providers, may be
 eager, and releases during shutdown. Cycles and provider-budget exhaustion fail
 closed. Do not build a controller or container layer around it.
 
+When the process has already constructed an application resource, bind it with
+`supply(app, provider, value)`. The provider must be app-scoped, the value is
+checked against that provider's inferred result type, and its `release` callback
+still owns shutdown. The binding follows `prefix`, middleware, docs, lifecycle,
+and server composition; supplying the same provider twice is rejected.
+
 ## Composition, lifecycle, and middleware
 
 Compose route tables as values:
@@ -282,7 +294,9 @@ task finishes. `setCookie` and
 fields. Never start long-lived work by
 dropping a Promise; use an owned lifecycle, background task, Worker, or process.
 
-`docs` adds a bundled offline UI and OpenAPI 3.1 JSON. Compiler route types
+`docs` adds a bundled offline UI and OpenAPI 3.1 JSON. HTTP and WebSocket
+operations share its `paths` catalog; WebSocket entries use GET, response 101,
+and `x-velar-transport: websocket`. Compiler route types
 and response helpers supply parameter, body, response, content-type, and static
 success-status schemas. Applicable framework-generated 400, 401, 413, 415, and
 422 responses are included automatically; a preceding `///` comment supplies
@@ -317,7 +331,7 @@ session belongs in the route table:
 import {WebSocketConnection} from "velar/websocket"
 
 server realtime:
-    @websocket(p"/worlds/{worldId:string}/realtime", connection: WebSocketConnection):
+    @websocket worldRealtime(p"/worlds/{worldId:string}/realtime", connection: WebSocketConnection):
         async for message in connection:
             await connection.send(message)
 ```
@@ -331,7 +345,8 @@ contains these routes rejects its legacy single `path` option and does not offer
 accepted sessions through `WebSocketServer.next()`.
 
 Set
-`maxBodyBytes` to the supplied application value. `origins` contains exact
+`maxBodyBytes` to the supplied application value. `host` is non-empty text of
+at most 255 code units without NUL. `origins` contains exact
 canonical HTTP/HTTPS origins. The default rejects any upgrade carrying
 `Origin`; no-Origin non-browser clients remain allowed. Use `["*"]` only for an
 intentional unrestricted policy. A rejected browser origin receives 403 before

package/skill/ai-skill-server.md

@@ -13,7 +13,7 @@ browser application activates `@velarscript/web`:
 ```json
 {
   "dependencies": {
-    "@velarscript/server": "0.19.1"
+    "@velarscript/server": "0.20.1"
   }
 }
 ```
@@ -24,27 +24,33 @@ browser application activates `@velarscript/web`:
   "entry": "src/main.vel",
   "outDir": "dist",
   "publicDir": "public",
-  "extensions": ["@velarscript/server"]
+  "extensions": ["@velarscript/server"],
+  "server": {
+    "configuration": "application.yml"
+  }
 }
 ```
 
 The Server application extension composes the Node capability. Do not list both
 extensions. Without `@velarscript/server`, `velar/server` is unavailable and
-root application configuration is not loaded.
+application configuration is not loaded.
 
-The conventional entry export is `start`. A different exported binding may be
-selected with the optional `server.app` manifest field. Source maps belong to
-the target-neutral top-level `build.sourceMaps` switch. Host, port, request limits, database locations, and
-other runtime settings never belong in `velar.json`.
+The selected entry source must start the application inside `@main`; there is
+no special exported startup binding. Source maps belong to the target-neutral
+top-level `build.sourceMaps` switch. `velar.json` stores only the project-relative
+configuration path. Host, port, request limits, database locations, and other
+runtime values remain in that YAML or JSON file.
 
 ## Convention-based application configuration
 
-The only conventional configuration file is root `application.yml`.
+`server.configuration` is required and is the single configuration source.
+The CLI's minimal template chooses root `application.yml`, but users may rename
+or move it by editing `velar.json`; the framework never scans conventional
+filenames.
 
 YAML and JSON enter the same checked runtime-Type boundary. Files are bounded;
-YAML is strict, rejects duplicate keys, and limits aliases. An explicit
-`.yml`, `.yaml`, or `.json` path is the escape hatch for deployment-specific
-configuration; other root filenames are never discovered by convention.
+YAML is strict, rejects duplicate keys, and limits aliases. The declared path
+must stay within the project and end in `.yml`, `.yaml`, or `.json`.
 
 The framework-owned server section is:
 
@@ -56,22 +62,24 @@ server:
 ```
 
 All three fields are optional. Their defaults are `127.0.0.1`, `3000`, and
-16 MiB. `application(app)` reads this section when the server starts:
+16 MiB. `application(app)` reads this section and creates the server; the
+entry owns its lifetime explicitly:
 
 ```velar
 import {application} from "velar/server"
+import {run} from "velar/serve"
 
 export server routes:
     @get(p"/health") => {status: "ready"}
 
-export const start = application(routes)
+@main:
+    const server = await application(routes)
+    await run(server)
 ```
 
 `velar dev`, `velar serve`, and the standalone `velar build` output use the
-same root configuration. CLI `--host` and Node `--port` overrides are not a
-second configuration channel. A missing conventional file uses the server
-defaults; when application-specific settings are required, load the full file
-with `configuration(Type)`, which requires the file to exist.
+same declared configuration. CLI `--host` and Node `--port` overrides are not
+a second configuration channel. A missing declared file fails closed.
 
 ## Typed application settings
 
@@ -93,11 +101,12 @@ type ApplicationSettings:
     server: ServerSettings
     database: DatabaseSettings
 
-export const settings = await configuration(ApplicationSettings)
+export async def loadSettings() -> ApplicationSettings:
+    return await configuration(ApplicationSettings)
 ```
 
-`configuration(Type, path=null, maxBytes=65536)` returns
-`Promise<Type>`. A non-null path must end in `.yml`, `.yaml`, or `.json`.
+`configuration(Type, maxBytes=65536)` returns `Promise<Type>` and always reads
+the manifest-declared path.
 The framework parses syntax; the application Runtime Type owns field names and
 types, and application validation still owns domain ranges and invariants.
 Environment variables may form an explicit deployment override layer, but
@@ -238,12 +247,12 @@ idempotent handling.
 ## Custom shared HTTP/WebSocket startup
 
 A service whose route table contains `@websocket` declarations may load the
-same typed configuration and export an exact zero-argument async startup
-function for the shared HTTP/WebSocket listener:
+same typed configuration and create the shared HTTP/WebSocket listener inside
+`@main`:
 
 ```velar fragment
 import {configuration} from "velar/server"
-import {listen} from "velar/websocket"
+import {listen, run} from "velar/websocket"
 
 type ServerSettings:
     host: string
@@ -253,21 +262,21 @@ type ServerSettings:
 type Settings:
     server: ServerSettings
 
-const settings = await configuration(Settings)
-
-export async def start():
-    return await listen({
+@main:
+    const settings = await configuration(Settings)
+    const server = await listen({
         host: settings.server.host,
         port: settings.server.port,
         http: routes,
         origins: ["https://app.example.com"],
         maxBodyBytes: settings.server.maxBodyBytes,
     })
+    await run(server)
 ```
 
-The result must be exactly `Promise<WebSocketServer>`. The launcher supplies no
-host, port, or body-limit arguments; the root application configuration remains
-the single runtime authority. Each `@websocket` RoutePattern owns its own path,
+The entry module itself is the executable artifact; the declared application
+configuration remains the single runtime authority. Each `@websocket`
+RoutePattern owns its own path,
 typed captures, admission inputs, and session handler, so this declarative mode
 does not accept the listener's legacy single `path` option.
 

package/skill/ai-skill-web.md

@@ -23,6 +23,15 @@ modules, and the `web` manifest key. Without that extension these are not Core
 syntax. Web visual builders are named imports from `velar/look`; there is no
 `Look.` namespace.
 
+Every word in that list is a contextual keyword that stays available as an
+ordinary name — except five. `mount`, `tick`, `viewport`, `scheme`, and `motion`
+are **reserved bindings**: `mount` and `tick` are real runtime entry points, and
+`viewport`, `scheme`, and `motion` name the Look media subjects, so a local
+binding can never shadow a media condition. A Web module refuses all five as
+binding names with `VEL3007`. Three of them are ordinary words for a Web author,
+so name a scroll container `scroller`, a colour setting `theme`, and an
+animation preference `reducedMotion`.
+
 `@` remains the language-wide annotation introducer, and `@name` is a context
 annotation with a compiler-owned compile-time role. Components own `@mounted:`
 and `@cleanup:`; Look owns conditions such as `@hover` and `@before`. They are

package/skill/ai-skill.md

@@ -75,7 +75,8 @@ considering source fallback. Other templates select their own framework brief. E
 `velar.json`, a `package.json` whose scripts are the gates, a `src/` tree, a
 passing test, and an `AGENTS.md`.
 
-Writing the manifest yourself: `formatVersion` is required, `extensions` may be
+Writing the manifest yourself: `formatVersion` is required, `kind` may be
+`application` or `library` (and defaults to `application`), `extensions` may be
 omitted by a project that loads none, `entry` defaults to `src/main.vel`,
 `outDir` to `dist`, and `publicDir` to `public`.
 
@@ -84,6 +85,7 @@ A Core project (CLI or library) loads no extensions:
 ```json
 {
   "formatVersion": 2,
+  "kind": "library",
   "entry": "src/main.vel",
   "extensions": []
 }