@atscript/typescript 0.1.26 → 0.1.27

package/README.md

@@ -0,0 +1,50 @@
+# @atscript/typescript
+
+TypeScript language extension for [Atscript](https://atscript.moost.org). Compiles `.as` files into `.d.ts` type declarations and `.js` runtime modules with full metadata, validation, and JSON Schema support.
+
+## Installation
+
+```bash
+pnpm add @atscript/typescript @atscript/core
+```
+
+For build-tool integration (Vite, Webpack, Rollup, esbuild, Rspack), also add:
+
+```bash
+pnpm add unplugin-atscript
+```
+
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx atscript-typescript-skill
+
+# Global (available across all your projects)
+npx atscript-typescript-skill --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "atscript-typescript-skill --postinstall"
+  }
+}
+```
+
+## Features
+
+- **Type declarations** — `.d.ts` files from `.as` interfaces and types
+- **Runtime metadata** — `.js` files with full metadata for validators and serializers
+- **JSON Schema** — Build, parse, and merge JSON schemas from annotated types
+- **Validation** — Validate data against types with plugin support
+- **Serialization** — JSON-safe round-trip serialization/deserialization
+- **CLI** — `asc` command for compiling `.as` files
+
+## Documentation
+
+Full documentation: [atscript.moost.org](https://atscript.moost.org)

package/dist/cli.cjs

@@ -1089,7 +1089,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build$1);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -1176,7 +1176,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 		const nameCounts = new Map();
 		const nodesByName = new Map();
-		for (const node of this.doc.nodes) if (node.__typeId != null && node.id) {
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
 			const name = node.id;
 			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
 			if (!nodesByName.has(name)) nodesByName.set(name, []);
@@ -1202,7 +1202,7 @@ else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}_
 	* meaning annotations target properties inside a referenced type.
 	*/ hasAdHocAnnotationsThroughRef() {
 		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
-		const prefix = this._propPath.join(".") + ".";
+		const prefix = `${this._propPath.join(".")}.`;
 		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
 		return false;
 	}
@@ -1316,7 +1316,7 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
-				const typeId = this.typeIds.get(node) ?? (node.__typeId != null ? node.id : undefined);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}

package/dist/index.cjs

@@ -1,4 +1,5 @@
 "use strict";
+Object.defineProperty(exports, '__esModule', { value: true });
 //#region rolldown:runtime
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -1086,7 +1087,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -1173,7 +1174,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 		const nameCounts = new Map();
 		const nodesByName = new Map();
-		for (const node of this.doc.nodes) if (node.__typeId != null && node.id) {
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
 			const name = node.id;
 			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
 			if (!nodesByName.has(name)) nodesByName.set(name, []);
@@ -1199,7 +1200,7 @@ else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}_
 	* meaning annotations target properties inside a referenced type.
 	*/ hasAdHocAnnotationsThroughRef() {
 		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
-		const prefix = this._propPath.join(".") + ".";
+		const prefix = `${this._propPath.join(".")}.`;
 		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
 		return false;
 	}
@@ -1313,7 +1314,7 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
-				const typeId = this.typeIds.get(node) ?? (node.__typeId != null ? node.id : undefined);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}
@@ -1870,8 +1871,5 @@ else return t.optional ? `${t.type} | true` : t.type;
 };
 
 //#endregion
-//#region packages/typescript/src/index.ts
-var src_default = tsPlugin;
-
-//#endregion
-module.exports = src_default;
+exports.default = tsPlugin
+exports.tsPlugin = tsPlugin

package/dist/index.d.ts

@@ -20,4 +20,4 @@ interface TTsPluginOptions {
 }
 declare const tsPlugin: (opts?: TTsPluginOptions) => TAtscriptPlugin;
 
-export { tsPlugin as default };
+export { tsPlugin as default, tsPlugin };

package/dist/index.mjs

@@ -1062,7 +1062,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;
@@ -1149,7 +1149,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 		const nameCounts = new Map();
 		const nodesByName = new Map();
-		for (const node of this.doc.nodes) if (node.__typeId != null && node.id) {
+		for (const node of this.doc.nodes) if (node.__typeId !== null && node.__typeId !== undefined && node.id) {
 			const name = node.id;
 			nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
 			if (!nodesByName.has(name)) nodesByName.set(name, []);
@@ -1175,7 +1175,7 @@ else for (let i = 0; i < nodes.length; i++) this.typeIds.set(nodes[i], `${name}_
 	* meaning annotations target properties inside a referenced type.
 	*/ hasAdHocAnnotationsThroughRef() {
 		if (!this._adHocAnnotations || this._propPath.length === 0) return false;
-		const prefix = this._propPath.join(".") + ".";
+		const prefix = `${this._propPath.join(".")}.`;
 		for (const key of this._adHocAnnotations.keys()) if (key.startsWith(prefix)) return true;
 		return false;
 	}
@@ -1289,7 +1289,7 @@ else {
 			case "type": {
 				const def = node.getDefinition();
 				const handle = this.toAnnotatedHandle(def, true);
-				const typeId = this.typeIds.get(node) ?? (node.__typeId != null ? node.id : undefined);
+				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);
 				return skipAnnotations ? handle : this.applyExpectAnnotations(handle, this.doc.evalAnnotationsForNode(node));
 			}
@@ -1846,8 +1846,4 @@ else return t.optional ? `${t.type} | true` : t.type;
 };
 
 //#endregion
-//#region packages/typescript/src/index.ts
-var src_default = tsPlugin;
-
-//#endregion
-export { src_default as default };
+export { tsPlugin as default, tsPlugin };

package/dist/utils.cjs

@@ -707,7 +707,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build$1);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;

package/dist/utils.mjs

@@ -706,7 +706,7 @@ function buildJsonSchema(type) {
 					const oneOf = d.type.items.map(build$1);
 					const mapping = {};
 					for (const [val, origPath] of Object.entries(disc.mapping)) {
-						const idx = Number.parseInt(origPath.split("/").pop());
+						const idx = Number.parseInt(origPath.split("/").pop(), 10);
 						const item = d.type.items[idx];
 						if (item.id && defs[item.id]) mapping[val] = `#/$defs/${item.id}`;
 else mapping[val] = origPath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -20,7 +20,7 @@
   },
   "bin": {
     "asc": "./cli.cjs",
-    "setup-skills": "./scripts/setup-skills.js"
+    "atscript-typescript-skill": "./scripts/setup-skills.js"
   },
   "files": [
     "dist",
@@ -57,14 +57,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@moostjs/event-cli": "^0.5.32",
-    "moost": "^0.5.32"
+    "@moostjs/event-cli": "^0.6.0",
+    "moost": "^0.6.0"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.26"
+    "@atscript/core": "^0.1.27"
   },
   "build": [
     {},

package/scripts/setup-skills.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /* prettier-ignore */
 import fs from 'fs'
-import path from 'path'
 import os from 'os'
+import path from 'path'
 import { fileURLToPath } from 'url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -17,17 +17,18 @@ if (!fs.existsSync(SKILL_SRC)) {
 }
 
 const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+  'Claude Code': { dir: '.claude/skills', global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor': { dir: '.cursor/skills', global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf': { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex': { dir: '.codex/skills', global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode': { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
 }
 
 const args = process.argv.slice(2)
 const isGlobal = args.includes('--global') || args.includes('-g')
 const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
+let installed = 0,
+  skipped = 0
 const installedDirs = []
 
 for (const [agentName, cfg] of Object.entries(AGENTS)) {
@@ -36,7 +37,10 @@ for (const [agentName, cfg] of Object.entries(AGENTS)) {
 
   // In postinstall mode: silently skip agents that aren't set up globally
   if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+    if (!fs.existsSync(agentRootDir)) {
+      skipped++
+      continue
+    }
   }
 
   const dest = path.join(targetBase, SKILL_NAME)
@@ -55,13 +59,17 @@ for (const [agentName, cfg] of Object.entries(AGENTS)) {
 if (!isGlobal && installedDirs.length > 0) {
   const gitignorePath = path.join(process.cwd(), '.gitignore')
   let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  try {
+    gitignoreContent = fs.readFileSync(gitignorePath, 'utf8')
+  } catch {}
   const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
   if (linesToAdd.length > 0) {
     const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
+    const block =
+      (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '') +
+      (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n') +
+      linesToAdd.join('\n') +
+      '\n'
     fs.appendFileSync(gitignorePath, block)
     console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
   }
@@ -70,7 +78,9 @@ if (!isGlobal && installedDirs.length > 0) {
 if (installed === 0 && isPostinstall) {
   // Silence is fine — no agents present, nothing to do
 } else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+  console.log(
+    'No agent directories detected. Try --global or run without it for project-local install.'
+  )
 } else if (installed === 0) {
   console.log('Nothing installed. Run without --global to install project-locally.')
 } else {

package/skills/atscript-typescript/SKILL.md

@@ -11,15 +11,15 @@ Atscript is a universal type and metadata description language. `@atscript/types
 
 Read the domain file that matches the task. Do not load all files — only what you need.
 
-| Domain | File | Load when… |
-|--------|------|------------|
-| Setup & configuration | [core.md](core.md) | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI |
-| `.as` file syntax | [syntax.md](syntax.md) | Writing `.as` files — interfaces, types, imports/exports, property syntax |
+| Domain                   | File                             | Load when…                                                                                  |
+| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| Setup & configuration    | [core.md](core.md)               | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI         |
+| `.as` file syntax        | [syntax.md](syntax.md)           | Writing `.as` files — interfaces, types, imports/exports, property syntax                   |
 | Annotations & primitives | [annotations.md](annotations.md) | Using built-in `@meta.*`/`@expect.*` annotations, defining custom annotations or primitives |
-| Code generation | [codegen.md](codegen.md) | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types |
-| Runtime type system | [runtime.md](runtime.md) | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType` |
-| Validation | [validation.md](validation.md) | Validating data, type guards, error handling, custom validator plugins |
-| Utility functions | [utilities.md](utilities.md) | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType` |
+| Code generation          | [codegen.md](codegen.md)         | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types      |
+| Runtime type system      | [runtime.md](runtime.md)         | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType`  |
+| Validation               | [validation.md](validation.md)   | Validating data, type guards, error handling, custom validator plugins                      |
+| Utility functions        | [utilities.md](utilities.md)     | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType`   |
 
 ## Quick reference
 
@@ -29,12 +29,20 @@ import tsPlugin from '@atscript/typescript'
 
 // Runtime utilities (used in app code)
 import {
-  defineAnnotatedType, isAnnotatedType, annotate,
-  Validator, ValidatorError,
-  buildJsonSchema, fromJsonSchema, mergeJsonSchemas,
-  serializeAnnotatedType, deserializeAnnotatedType,
-  flattenAnnotatedType, createDataFromAnnotatedType,
-  forAnnotatedType, throwFeatureDisabled,
+  defineAnnotatedType,
+  isAnnotatedType,
+  annotate,
+  Validator,
+  ValidatorError,
+  buildJsonSchema,
+  fromJsonSchema,
+  mergeJsonSchemas,
+  serializeAnnotatedType,
+  deserializeAnnotatedType,
+  flattenAnnotatedType,
+  createDataFromAnnotatedType,
+  forAnnotatedType,
+  throwFeatureDisabled,
 } from '@atscript/typescript/utils'
 
 // CLI

package/skills/atscript-typescript/annotations.md

@@ -6,36 +6,36 @@
 
 ### `@meta.*` — Metadata Annotations
 
-| Annotation | Arguments | Description |
-|------------|-----------|-------------|
-| `@meta.label` | `text: string` | Human-readable label for UI, logs, documentation |
-| `@meta.id` | `name?: string` (optional) | Mark field as unique identifier; optional custom name |
-| `@meta.description` | `text: string` | Detailed description of a field or entity |
-| `@meta.documentation` | `text: string` | Multi-line docs (Markdown). Multiple allowed — each appends |
-| `@meta.placeholder` | `text: string` | Placeholder for UI input fields (props/types only) |
-| `@meta.sensitive` | *(none)* | Mark as sensitive (passwords, API keys). Strips from serialization |
-| `@meta.readonly` | *(none)* | Mark as read-only |
-| `@meta.required` | `message?: string` | Required field. Strings: non-whitespace. Booleans: must be `true` |
-| `@meta.default` | `value: string` | Default value (strings as-is, others parsed as JSON) |
-| `@meta.example` | `value: string` | Example value (strings as-is, others parsed as JSON) |
-| `@meta.isKey` | *(none)* | Mark field as key inside array (string/number types only) |
+| Annotation            | Arguments                  | Description                                                        |
+| --------------------- | -------------------------- | ------------------------------------------------------------------ |
+| `@meta.label`         | `text: string`             | Human-readable label for UI, logs, documentation                   |
+| `@meta.id`            | `name?: string` (optional) | Mark field as unique identifier; optional custom name              |
+| `@meta.description`   | `text: string`             | Detailed description of a field or entity                          |
+| `@meta.documentation` | `text: string`             | Multi-line docs (Markdown). Multiple allowed — each appends        |
+| `@meta.placeholder`   | `text: string`             | Placeholder for UI input fields (props/types only)                 |
+| `@meta.sensitive`     | _(none)_                   | Mark as sensitive (passwords, API keys). Strips from serialization |
+| `@meta.readonly`      | _(none)_                   | Mark as read-only                                                  |
+| `@meta.required`      | `message?: string`         | Required field. Strings: non-whitespace. Booleans: must be `true`  |
+| `@meta.default`       | `value: string`            | Default value (strings as-is, others parsed as JSON)               |
+| `@meta.example`       | `value: string`            | Example value (strings as-is, others parsed as JSON)               |
+| `@meta.isKey`         | _(none)_                   | Mark field as key inside array (string/number types only)          |
 
 ### `@expect.*` — Validation Constraints
 
-| Annotation | Arguments | Applies To | Description |
-|------------|-----------|-----------|-------------|
-| `@expect.minLength` | `length: number`, `message?: string` | string, array | Minimum length |
-| `@expect.maxLength` | `length: number`, `message?: string` | string, array | Maximum length |
-| `@expect.min` | `minValue: number`, `message?: string` | number | Minimum value |
-| `@expect.max` | `maxValue: number`, `message?: string` | number | Maximum value |
-| `@expect.int` | *(none)* | number | Must be integer |
-| `@expect.pattern` | `pattern: string`, `flags?: string`, `message?: string` | string | Regex validation. **Multiple allowed** (all must pass) |
+| Annotation          | Arguments                                               | Applies To    | Description                                            |
+| ------------------- | ------------------------------------------------------- | ------------- | ------------------------------------------------------ |
+| `@expect.minLength` | `length: number`, `message?: string`                    | string, array | Minimum length                                         |
+| `@expect.maxLength` | `length: number`, `message?: string`                    | string, array | Maximum length                                         |
+| `@expect.min`       | `minValue: number`, `message?: string`                  | number        | Minimum value                                          |
+| `@expect.max`       | `maxValue: number`, `message?: string`                  | number        | Maximum value                                          |
+| `@expect.int`       | _(none)_                                                | number        | Must be integer                                        |
+| `@expect.pattern`   | `pattern: string`, `flags?: string`, `message?: string` | string        | Regex validation. **Multiple allowed** (all must pass) |
 
 ### `@emit.*` — Build-time Directives
 
-| Annotation | Applies To | Description |
-|------------|-----------|-------------|
-| `@emit.jsonSchema` | interface | Pre-compute and embed JSON Schema at build time |
+| Annotation         | Applies To | Description                                     |
+| ------------------ | ---------- | ----------------------------------------------- |
+| `@emit.jsonSchema` | interface  | Pre-compute and embed JSON Schema at build time |
 
 ## Custom Annotations
 
@@ -102,10 +102,10 @@ new AnnotationSpec({
   ],
 
   // Allow multiple instances on the same target
-  multiple: true,               // default: false
+  multiple: true, // default: false
 
   // How duplicates merge: 'replace' (last wins) or 'append' (collect into array)
-  mergeStrategy: 'append',      // default: 'replace'
+  mergeStrategy: 'append', // default: 'replace'
 
   // Human-readable description
   description: 'What this annotation does',
@@ -124,13 +124,13 @@ new AnnotationSpec({
 
 Each argument accepts:
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Argument name (used in metadata object key) |
-| `type` | `'string' \| 'number' \| 'boolean'` | Expected type |
-| `optional` | `boolean` | Whether the argument can be omitted |
-| `description` | `string` | Human-readable description |
-| `values` | `string[]` | Allowed values (enum-like constraint) |
+| Field         | Type                                | Description                                 |
+| ------------- | ----------------------------------- | ------------------------------------------- |
+| `name`        | `string`                            | Argument name (used in metadata object key) |
+| `type`        | `'string' \| 'number' \| 'boolean'` | Expected type                               |
+| `optional`    | `boolean`                           | Whether the argument can be omitted         |
+| `description` | `string`                            | Human-readable description                  |
+| `values`      | `string[]`                          | Allowed values (enum-like constraint)       |
 
 ### How Annotations Map to Runtime Metadata
 
@@ -140,6 +140,7 @@ Each argument accepts:
 - **`multiple: true`** → metadata value is an array
 
 Example: `@api.endpoint "/users" "GET"` becomes:
+
 ```ts
 metadata.get('api.endpoint') // → { path: "/users", method: "GET" }
 ```
@@ -200,26 +201,26 @@ export default defineConfig({
 
 ### `TPrimitiveConfig` Options
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `TPrimitiveTypeDef` | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex type |
-| `tags` | `string[]` | Custom tags for categorization |
-| `documentation` | `string` | Documentation string |
-| `expect` | object | Built-in validation constraints |
-| `extensions` | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types accessible via dot notation |
+| Field           | Type                                        | Description                                                                                      |
+| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `type`          | `TPrimitiveTypeDef`                         | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex type |
+| `tags`          | `string[]`                                  | Custom tags for categorization                                                                   |
+| `documentation` | `string`                                    | Documentation string                                                                             |
+| `expect`        | object                                      | Built-in validation constraints                                                                  |
+| `extensions`    | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types accessible via dot notation                                                            |
 
 ### `expect` Validation on Primitives
 
-| Field | Applies To | Description |
-|-------|-----------|-------------|
-| `min` | number | Minimum value |
-| `max` | number | Maximum value |
-| `int` | number | Must be integer |
-| `minLength` | string, array | Minimum length |
-| `maxLength` | string, array | Maximum length |
-| `pattern` | string | Regex pattern(s) |
-| `required` | string, boolean | Non-empty / must be true |
-| `message` | any | Custom error message for pattern |
+| Field       | Applies To      | Description                      |
+| ----------- | --------------- | -------------------------------- |
+| `min`       | number          | Minimum value                    |
+| `max`       | number          | Maximum value                    |
+| `int`       | number          | Must be integer                  |
+| `minLength` | string, array   | Minimum length                   |
+| `maxLength` | string, array   | Maximum length                   |
+| `pattern`   | string          | Regex pattern(s)                 |
+| `required`  | string, boolean | Non-empty / must be true         |
+| `message`   | any             | Custom error message for pattern |
 
 ### Usage in `.as` Files
 

package/skills/atscript-typescript/codegen.md

@@ -6,10 +6,10 @@
 
 Each `.as` file produces two outputs:
 
-| Output | Generated By | Contains |
-|--------|-------------|----------|
+| Output      | Generated By                   | Contains                                                                                             |
+| ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
 | `*.as.d.ts` | `npx asc -f dts` or build tool | TypeScript type declarations — interfaces become `declare class` with static type/metadata/validator |
-| `*.as.js` | Build tool (unplugin-atscript) | Runtime module — classes with full type definitions, metadata maps, and validator factories |
+| `*.as.js`   | Build tool (unplugin-atscript) | Runtime module — classes with full type definitions, metadata maps, and validator factories          |
 
 ## `.d.ts` Output
 
@@ -31,9 +31,12 @@ Generates `user.as.d.ts`:
 
 ```ts
 import type {
-  TAtscriptTypeObject, TAtscriptAnnotatedType,
-  TMetadataMap, Validator, TValidatorOptions
-} from "@atscript/typescript/utils"
+  TAtscriptTypeObject,
+  TAtscriptAnnotatedType,
+  TMetadataMap,
+  Validator,
+  TValidatorOptions,
+} from '@atscript/typescript/utils'
 
 export declare class User {
   name: string
@@ -48,7 +51,7 @@ export declare class User {
   static toExampleData?: () => any
 }
 
-export type Status = "active" | "inactive"
+export type Status = 'active' | 'inactive'
 declare namespace Status {
   const __is_atscript_annotated_type: true
   const type: TAtscriptTypeComplex<Status>
@@ -60,6 +63,7 @@ declare namespace Status {
 ```
 
 Key points:
+
 - **Interfaces** become `declare class` — so they work both as types and runtime values
 - **Types** become a `type` alias + a companion `namespace` with runtime statics
 - Each has `type`, `metadata`, `validator()`, `toJsonSchema()`, and `toExampleData()` statics
@@ -92,7 +96,7 @@ declare global {
     'expect.minLength': { length: number; message?: string }
     // ... all annotations used in your project
   }
-  type AtscriptPrimitiveTags = "string" | "number" | "boolean" | "null"
+  type AtscriptPrimitiveTags = 'string' | 'number' | 'boolean' | 'null'
 }
 ```
 
@@ -108,8 +112,8 @@ This file is **auto-generated** based on the annotations actually used across al
 
 Generated files use these import paths:
 
-| Import | Source |
-|--------|--------|
+| Import                       | Source                                            |
+| ---------------------------- | ------------------------------------------------- |
 | `@atscript/typescript/utils` | Runtime utilities (used by generated `.js` files) |
 
 When importing from `.as` files in your TypeScript code: