@atscript/core 0.1.27 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/core",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Core library for Atscript parsing and file generation.",
   "keywords": [
     "annotations",
@@ -20,8 +20,13 @@
     "url": "git+https://github.com/moostjs/atscript.git",
     "directory": "packages/core"
   },
+  "bin": {
+    "atscript-core-skill": "./scripts/setup-skills.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -46,6 +51,7 @@
   },
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest"
+    "test": "vitest",
+    "setup-skills": "node ./scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'atscript-core'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+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') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global)
+
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  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'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence — no agents present
+} 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.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/atscript-core/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: atscript-core
+description: Use when working with @atscript/core — configuring atscript.config.ts with defineConfig, defining custom AnnotationSpec annotations, creating custom TPrimitiveConfig primitives, building TAtscriptPlugin plugins with config/resolve/load/onDocument/render/buildEnd hooks, understanding built-in @meta.* @expect.* @ui.* @db.* @emit.* annotations, or working with AtscriptDoc/AtscriptRepo APIs.
+---
+
+# @atscript/core
+
+The foundation package for Atscript — a universal type and metadata description language. Provides the parser, AST, annotation system, plugin architecture, and all built-in annotations and primitives that language extensions (TypeScript, Python, etc.) build upon.
+
+## How to use this skill
+
+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`, understanding the package structure |
+| Annotations reference    | [annotations.md](annotations.md) | Using or defining `@meta.*`, `@expect.*`, `@ui.*`, `@db.*`, `@emit.*` annotations |
+| Primitives reference     | [primitives.md](primitives.md)   | Using built-in primitives (`string.email`, `number.int`) or defining custom ones  |
+| Plugin development       | [plugins.md](plugins.md)         | Creating plugins with `createAtscriptPlugin`, implementing hooks                  |
+
+## Quick reference
+
+```ts
+// Configuration
+import { defineConfig, AnnotationSpec } from '@atscript/core'
+
+// Plugin creation
+import { createAtscriptPlugin } from '@atscript/core'
+
+// AST / document types (for plugin authors)
+import { AtscriptDoc, AtscriptRepo } from '@atscript/core'
+```

package/skills/atscript-core/annotations.md

@@ -0,0 +1,157 @@
+# Annotations Reference — @atscript/core
+
+> Complete reference for all built-in annotations and the `AnnotationSpec` API for defining custom ones.
+
+## Built-in Annotation Namespaces
+
+### `@meta.*` — Semantic Metadata
+
+| Annotation            | Arguments            | Multiple | NodeType         | Description                                                |
+| --------------------- | -------------------- | -------- | ---------------- | ---------------------------------------------------------- |
+| `@meta.label`         | `text: string`       | no       | any              | Human-readable label for UI, logs, documentation           |
+| `@meta.id`            | _(none)_             | no       | prop             | Mark field as unique identifier; multiple = composite PK   |
+| `@meta.description`   | `text: string`       | no       | any              | Detailed description                                       |
+| `@meta.documentation` | `text: string`       | **yes**  | any              | Multi-line Markdown docs (each appends a line)             |
+| `@meta.sensitive`     | _(none)_             | no       | prop, type       | Sensitive data (passwords, keys) — hidden in logs/UI       |
+| `@meta.readonly`      | _(none)_             | no       | prop, type       | Read-only field                                            |
+| `@meta.required`      | `message?: string`   | no       | string, boolean  | Required: strings must be non-whitespace; booleans `true`  |
+| `@meta.default`       | `value: string`      | no       | prop, type       | Default value (strings as-is, others parsed as JSON)       |
+| `@meta.example`       | `value: string`      | no       | prop, type       | Example value (strings as-is, others parsed as JSON)       |
+
+### `@expect.*` — Validation Constraints
+
+| Annotation          | Arguments                                               | Multiple | Applies To    | Description                 |
+| ------------------- | ------------------------------------------------------- | -------- | ------------- | --------------------------- |
+| `@expect.minLength` | `length: number`, `message?: string`                    | no       | string, array | Minimum length              |
+| `@expect.maxLength` | `length: number`, `message?: string`                    | no       | string, array | Maximum length              |
+| `@expect.min`       | `minValue: number`, `message?: string`                  | no       | number        | Minimum value               |
+| `@expect.max`       | `maxValue: number`, `message?: string`                  | no       | number        | Maximum value               |
+| `@expect.int`       | _(none)_                                                | no       | number        | Must be integer             |
+| `@expect.pattern`   | `pattern: string`, `flags?: string`, `message?: string` | **yes** (append) | string | Regex validation     |
+| `@expect.array.key` | _(none)_                                                | no       | string, number | Key field in arrays         |
+
+### `@ui.*` — UI / Presentation Hints
+
+| Annotation        | Arguments                      | Multiple        | NodeType                | Description                              |
+| ----------------- | ------------------------------ | --------------- | ----------------------- | ---------------------------------------- |
+| `@ui.placeholder` | `text: string`                 | no              | prop, type              | Input placeholder text                   |
+| `@ui.component`   | `name: string`                 | no              | prop, type              | UI component hint (`"select"`, etc.)     |
+| `@ui.hidden`      | _(none)_                       | no              | prop, type, interface   | Hide from UI forms/tables                |
+| `@ui.group`       | `name: string`                 | no              | prop                    | Group fields into form sections          |
+| `@ui.order`       | `order: number`                | no              | prop                    | Display order (lower = first)            |
+| `@ui.width`       | `width: string`                | no              | prop, type              | Layout hint (`"half"`, `"full"`, etc.)   |
+| `@ui.icon`        | `name: string`                 | no              | prop, type, interface   | Icon hint                                |
+| `@ui.hint`        | `text: string`                 | no              | prop, type              | Help text / tooltip                      |
+| `@ui.disabled`    | _(none)_                       | no              | prop, type              | Non-interactive field                    |
+| `@ui.type`        | `type: string`                 | no              | prop, type              | Input type (`"textarea"`, `"password"`)  |
+| `@ui.attr`        | `key: string`, `value: string` | **yes** (append) | prop, type, interface  | Arbitrary HTML/component attribute       |
+| `@ui.class`       | `names: string`                | **yes** (append) | prop, type, interface  | CSS class names                          |
+| `@ui.style`       | `css: string`                  | **yes** (append) | prop, type, interface  | Inline CSS styles                        |
+
+### `@db.*` — Database Schema
+
+| Annotation          | Arguments                    | Multiple        | NodeType  | Description                              |
+| ------------------- | ---------------------------- | --------------- | --------- | ---------------------------------------- |
+| `@db.table`         | `name: string \| true`       | no              | interface | Database table/collection name           |
+| `@db.schema`        | `name: string`               | no              | interface | Database schema (PostgreSQL, etc.)       |
+| `@db.index.plain`   | `name?: string`, `sort?: string` | **yes** (append) | prop  | Standard index (shared name = compound)  |
+| `@db.index.unique`  | `name?: string`              | **yes** (append) | prop      | Unique constraint index                  |
+| `@db.index.fulltext`| `name?: string`              | **yes** (append) | prop      | Fulltext search index                    |
+| `@db.column`        | `name: string`               | no              | prop      | Override database column name            |
+| `@db.default.value` | `value: string`              | no              | prop      | Static default value                     |
+| `@db.default.fn`    | `fn: string`                 | no              | prop      | Database function for default            |
+| `@db.ignore`        | _(none)_                     | no              | prop      | Exclude field from database              |
+
+### `@emit.*` — Build-time Directives
+
+| Annotation         | NodeType  | Description                                     |
+| ------------------ | --------- | ----------------------------------------------- |
+| `@emit.jsonSchema` | interface | Pre-compute and embed JSON Schema at build time |
+
+## Custom Annotations
+
+Define in `atscript.config.ts` under the `annotations` key:
+
+```ts
+import { defineConfig, AnnotationSpec } from '@atscript/core'
+
+export default defineConfig({
+  annotations: {
+    // Flat: @tag "value"
+    tag: new AnnotationSpec({
+      multiple: true,
+      mergeStrategy: 'append',
+      argument: { name: 'value', type: 'string' },
+      description: 'Tag for categorization',
+    }),
+
+    // Namespaced: @api.deprecated "Use v2 instead"
+    api: {
+      deprecated: new AnnotationSpec({
+        argument: { name: 'message', type: 'string', optional: true },
+        nodeType: ['prop', 'interface'],
+        description: 'Mark as deprecated',
+      }),
+    },
+  },
+})
+```
+
+### `AnnotationSpec` Options
+
+```ts
+new AnnotationSpec({
+  description?: string,          // IntelliSense hover text
+  nodeType?: ('interface' | 'type' | 'prop')[],  // Where it can be applied
+  defType?: string[],            // Restrict to value types: 'string', 'number', etc.
+
+  // Arguments
+  argument?: TAnnotationArgument | TAnnotationArgument[],
+  // Each: { name, type: 'string'|'number'|'boolean', optional?, description?, values? }
+
+  // Multiplicity
+  multiple?: boolean,            // Can appear more than once (default: false)
+  mergeStrategy?: 'replace' | 'append',  // How values merge on inheritance (default: 'replace')
+
+  // Advanced
+  validate?: (mainToken, args, doc) => TMessages | undefined,  // Custom validation
+  modify?: (mainToken, args, doc) => void,  // AST modification after parsing
+})
+```
+
+### How Annotations Map to Runtime Values
+
+| Config                          | Metadata value type          |
+| ------------------------------- | ---------------------------- |
+| No arguments                    | `true` (boolean flag)        |
+| Single argument                 | The argument value directly  |
+| Multiple named arguments        | `{ name1: val1, name2: val2 }` |
+| `multiple: true`                | Array of the above           |
+| `multiple: true` + `append`     | Concatenated array on merge  |
+
+### Merge Strategies
+
+When annotations inherit (type → prop, ad-hoc annotate blocks):
+
+- **replace** (default) — higher-priority annotation replaces lower entirely
+- **append** — values from both sides concatenate into a single array
+
+## Annotation Resolution
+
+```ts
+import { resolveAnnotation } from '@atscript/core'
+
+// Looks up 'ui.placeholder' in the annotation tree
+const spec = resolveAnnotation('ui.placeholder', config.annotations)
+// Returns AnnotationSpec or undefined
+```
+
+The function splits the dotted name and walks the `TAnnotationsTree` hierarchy.
+
+## Best Practices
+
+- Use namespaced annotations (`@ns.name`) to avoid collisions
+- Set `nodeType` to catch misuse early (e.g., `@db.table` only on interfaces)
+- Use `mergeStrategy: 'append'` for annotations that accumulate (patterns, tags, styles)
+- Use `validate` for complex cross-field checks (e.g., `@db.ignore` conflicts with `@meta.id`)
+- Keep `description` concise — it shows in IDE hover tooltips

package/skills/atscript-core/core.md

@@ -0,0 +1,125 @@
+# Setup & Configuration — @atscript/core
+
+> How to install, configure, and understand the @atscript/core package.
+
+## Overview
+
+`@atscript/core` is the foundation of the Atscript ecosystem. It provides:
+- Parser for `.as` files → AST
+- Annotation system (`AnnotationSpec`, annotation trees)
+- Primitive type system
+- Plugin architecture
+- Built-in annotations (`@meta.*`, `@expect.*`, `@ui.*`, `@db.*`, `@emit.*`)
+- Built-in primitives (`string`, `number`, `boolean`, `null`, `void`, `phantom` + extensions)
+
+Language extensions like `@atscript/typescript` build on top of core.
+
+## Installation
+
+```bash
+npm install @atscript/core
+```
+
+## Configuration
+
+Create `atscript.config.ts` (or `.js`) at your project root:
+
+```ts
+import { defineConfig } from '@atscript/core'
+import tsPlugin from '@atscript/typescript'
+
+export default defineConfig({
+  rootDir: 'src',
+  plugins: [tsPlugin()],
+
+  // Optional: custom annotations
+  annotations: {
+    myNamespace: {
+      myAnnotation: new AnnotationSpec({ ... }),
+    },
+  },
+
+  // Optional: custom primitives
+  primitives: {
+    currency: { type: 'string', annotations: { 'expect.pattern': { pattern: '^\\d+\\.\\d{2}$' } } },
+  },
+
+  // Optional: how unknown annotations are handled
+  unknownAnnotation: 'error', // 'error' (default) | 'warn' | 'allow'
+
+  // Optional: file patterns
+  include: ['**/*.as'],
+  exclude: ['**/node_modules/**'],
+})
+```
+
+### `TAtscriptConfig` Fields
+
+| Field               | Type                          | Description                                    |
+| ------------------- | ----------------------------- | ---------------------------------------------- |
+| `rootDir`           | `string`                      | Root directory for `.as` files                 |
+| `entries`           | `string[]`                    | Explicit entry files (instead of auto-discover) |
+| `plugins`           | `TAtscriptPlugin[]`           | Plugins to load (order matters)                |
+| `annotations`       | `TAnnotationsTree`            | Custom annotation definitions                  |
+| `primitives`        | `Record<string, TPrimitiveConfig>` | Custom primitive type definitions         |
+| `unknownAnnotation` | `'error' \| 'warn' \| 'allow'` | How to handle unrecognized annotations       |
+| `include`           | `string[]`                    | Glob patterns to include                       |
+| `exclude`           | `string[]`                    | Glob patterns to exclude                       |
+| `format`            | `string`                      | Output format (set by CLI or build tool)       |
+| `outDir`            | `string`                      | Output directory                               |
+
+## Package Exports
+
+```ts
+// Configuration
+export { defineConfig } from '@atscript/core'
+
+// Annotations
+export { AnnotationSpec, isAnnotationSpec, resolveAnnotation } from '@atscript/core'
+
+// Config types
+export type { TAtscriptConfig, TAnnotationsTree } from '@atscript/core'
+
+// Plugin system
+export { createAtscriptPlugin } from '@atscript/core'
+export type { TAtscriptPlugin, TPluginOutput } from '@atscript/core'
+export { DEFAULT_FORMAT } from '@atscript/core'
+
+// Document & Repo (for plugin authors)
+export { AtscriptDoc } from '@atscript/core'
+export { AtscriptRepo } from '@atscript/core'
+
+// Parser nodes (for plugin authors)
+export { /* node type guards and types */ } from '@atscript/core'
+
+// Build utilities
+export { build } from '@atscript/core'
+```
+
+## Architecture
+
+```
+atscript.config.ts
+  └─ defineConfig({ plugins, annotations, primitives })
+       └─ Plugins merge configs via defu (deep defaults)
+            └─ AtscriptRepo orchestrates parsing
+                 └─ AtscriptDoc per .as file (AST + metadata)
+                      └─ Plugins render output (render hook)
+                           └─ Plugins aggregate (buildEnd hook)
+```
+
+Plugins execute in array order. Each plugin's `config()` output is merged using `defu`, so multiple plugins can contribute annotations and primitives without conflicts.
+
+## Annotation Namespaces (Built-in)
+
+The core ships five annotation namespaces:
+
+| Namespace  | Purpose                            | Example                    |
+| ---------- | ---------------------------------- | -------------------------- |
+| `meta.*`   | Semantic metadata                  | `@meta.label "Name"`       |
+| `expect.*` | Validation constraints             | `@expect.min 0`            |
+| `ui.*`     | Presentation / UI hints            | `@ui.placeholder "Enter…"` |
+| `db.*`     | Database schema                    | `@db.table "users"`        |
+| `emit.*`   | Build-time directives              | `@emit.jsonSchema`         |
+
+See [annotations.md](annotations.md) for the full reference.

package/skills/atscript-core/plugins.md

@@ -0,0 +1,206 @@
+# Plugin Development — @atscript/core
+
+> How to create Atscript plugins that add annotations, primitives, and code generators.
+
+## Concepts
+
+A plugin is a plain object implementing `TAtscriptPlugin` — a `name` plus optional hooks. Plugins extend Atscript by adding annotations, primitives, and output generators without modifying the parser.
+
+## Creating a Plugin
+
+```ts
+import { createAtscriptPlugin, AnnotationSpec } from '@atscript/core'
+
+export const myPlugin = () =>
+  createAtscriptPlugin({
+    name: 'my-plugin',
+
+    // Add annotations and primitives
+    config(config) {
+      return {
+        annotations: {
+          api: {
+            deprecated: new AnnotationSpec({
+              description: 'Mark as deprecated',
+              argument: { name: 'message', type: 'string', optional: true },
+            }),
+          },
+        },
+      }
+    },
+
+    // Generate output files
+    render(doc, format) {
+      if (format === 'json') {
+        return [{ fileName: `${doc.name}.json`, content: JSON.stringify(doc.metadata) }]
+      }
+      return []
+    },
+  })
+```
+
+`createAtscriptPlugin` is a type-safe identity function — returns the object as-is but provides IntelliSense on hook signatures.
+
+## Registering Plugins
+
+```ts
+import { defineConfig } from '@atscript/core'
+import { myPlugin } from './plugins/my-plugin'
+
+export default defineConfig({
+  rootDir: 'src',
+  plugins: [myPlugin()],
+})
+```
+
+Plugins execute in array order. Each plugin's `config()` output is merged with accumulated config using `defu` (deep defaults).
+
+## The TAtscriptPlugin Interface
+
+```ts
+interface TAtscriptPlugin {
+  name: string
+  config?(config: TAtscriptConfig): TAtscriptConfig | undefined
+  resolve?(id: string): string | undefined
+  load?(id: string): string | undefined
+  onDocument?(doc: AtscriptDoc): void
+  render?(doc: AtscriptDoc, format: string): TPluginOutput[]
+  buildEnd?(output: TOutput[], format: string, repo: AtscriptRepo): void
+}
+```
+
+All hooks except `name` are optional. Hooks can be sync or async.
+
+## Hook Reference
+
+### `config(config)`
+
+Called once during initialization. Return additional config to merge (annotations, primitives). Multiple plugins merge via `defu`.
+
+```ts
+config(config) {
+  return {
+    primitives: {
+      url: { type: 'string', annotations: { 'expect.pattern': { pattern: '^https?://' } } },
+    },
+    annotations: {
+      cache: { ttl: new AnnotationSpec({ argument: { name: 'seconds', type: 'number' } }) },
+    },
+  }
+}
+```
+
+### `resolve(id)`
+
+Remap or virtualize module paths. Return a new path string or `undefined` to skip.
+
+```ts
+resolve(id) {
+  if (id === '@my-lib/types') return '/path/to/virtual-types.as'
+}
+```
+
+### `load(id)`
+
+Provide virtual file content. Return `.as` source string or `undefined`.
+
+```ts
+load(id) {
+  if (id === '/virtual/base-entity.as') {
+    return `export interface BaseEntity { id: string.uuid }`
+  }
+}
+```
+
+### `onDocument(doc)`
+
+Post-process a parsed document. Access the AST, inject virtual props, run checks.
+
+```ts
+onDocument(doc) {
+  // Access parsed interfaces
+  for (const [name, node] of doc.interfaces) {
+    // Inspect or modify the AST
+  }
+}
+```
+
+### `render(doc, format)`
+
+Generate output files for each document. Return `TPluginOutput[]`.
+
+```ts
+render(doc, format) {
+  if (format === 'dts' || format === DEFAULT_FORMAT) {
+    return [{ fileName: `${doc.name}.d.ts`, content: generateTypes(doc) }]
+  }
+  return []
+}
+```
+
+The `DEFAULT_FORMAT` constant is the format used when saving `.as` files in an editor. Check for it alongside your plugin's format strings.
+
+### `buildEnd(output, format, repo)`
+
+Called after all documents are rendered. Aggregate across all docs — useful for global type declarations, index files, etc.
+
+```ts
+buildEnd(output, format, repo) {
+  // repo.getUsedAnnotations() — all annotation specs registered
+  // output — array of { doc, files } from render phase
+}
+```
+
+## AtscriptDoc API (Key Methods)
+
+| Method / Property       | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `doc.name`              | File name (without extension)                    |
+| `doc.path`              | Full file path                                   |
+| `doc.interfaces`        | Map of interface names → AST nodes               |
+| `doc.types`             | Map of type names → AST nodes                    |
+| `doc.imports`           | Import declarations                              |
+| `doc.exports`           | Export declarations                               |
+| `doc.unwindType(id, chain)` | Resolve a type reference to its definition   |
+
+## AtscriptRepo API (Key Methods)
+
+| Method / Property              | Description                                    |
+| ------------------------------ | ---------------------------------------------- |
+| `repo.getUsedAnnotations()`    | Iterator of all registered annotation specs    |
+| `repo.documents`               | Map of all parsed documents                    |
+| `repo.config`                  | Merged configuration                           |
+
+## Common Patterns
+
+### Annotation-only plugin
+
+Just `config()` — the simplest plugin type:
+
+```ts
+export const tagsPlugin = () =>
+  createAtscriptPlugin({
+    name: 'tags',
+    config: () => ({
+      annotations: {
+        tag: new AnnotationSpec({
+          multiple: true,
+          mergeStrategy: 'append',
+          argument: { name: 'value', type: 'string' },
+        }),
+      },
+    }),
+  })
+```
+
+### Full language extension
+
+`config()` + `render()` + `buildEnd()` — see `@atscript/typescript` for the reference implementation.
+
+## Best Practices
+
+- Keep plugin names unique and descriptive
+- Use `config()` for annotations/primitives, not hardcoded checks
+- Check `format` in `render()` — plugins may be called with different formats
+- Use `DEFAULT_FORMAT` for output that's essential to the dev experience (e.g., type declarations)
+- Return empty array from `render()` when format doesn't match