@atscript/mongo 0.1.27 → 0.1.28

package/dist/index.mjs

@@ -19,15 +19,10 @@ const analyzers = [
 	"lucene.russian",
 	"lucene.arabic"
 ];
-const annotations = { mongo: {
+const annotations = {
 	collection: new AnnotationSpec({
-		description: "Defines a **MongoDB collection**. This annotation is required to mark an interface as a collection.\n\n- Automatically enforces a **non-optional** `_id` field.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n- Ensures that `_id` is included if not explicitly defined.\n\n**Example:**\n```atscript\n@mongo.collection \"users\"\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
 		nodeType: ["interface"],
-		argument: {
-			name: "name",
-			type: "string",
-			description: "The **name of the MongoDB collection**."
-		},
 		validate(token, args, doc) {
 			const parent = token.parentNode;
 			const struc = parent?.getDefinition();
@@ -36,7 +31,7 @@ const annotations = { mongo: {
 				const _id = parent.props.get("_id");
 				const isOptional = !!_id.token("optional");
 				if (isOptional) errors.push({
-					message: `[mongo] _id can't be optional in Mongo Collection`,
+					message: `[db.mongo] _id can't be optional in Mongo Collection`,
 					severity: 1,
 					range: _id.token("identifier").range
 				});
@@ -48,7 +43,7 @@ const annotations = { mongo: {
 					if (isPrimitive(def) && !["string", "number"].includes(def.config.type)) wrongType = true;
 				} else wrongType = true;
 				if (wrongType) errors.push({
-					message: `[mongo] _id must be of type string, number or mongo.objectId`,
+					message: `[db.mongo] _id must be of type string, number or mongo.objectId`,
 					severity: 1,
 					range: _id.token("identifier").range
 				});
@@ -74,43 +69,19 @@ const annotations = { mongo: {
 			description: "On/Off the automatic index creation"
 		}
 	}),
-	index: {
-		plain: new AnnotationSpec({
-			description: "Defines a **standard MongoDB index** on a field.\n\n- Improves query performance on indexed fields.\n- Can be used for **single-field** or **compound** indexes.\n\n**Example:**\n```atscript\n@mongo.index.plain \"departmentIndex\"\ndepartment: string\n```\n",
-			multiple: true,
-			nodeType: ["prop"],
-			argument: {
-				optional: true,
-				name: "indexName",
-				type: "string",
-				description: "The **name of the index** (optional). If omitted, property name is used."
-			}
-		}),
-		unique: new AnnotationSpec({
-			description: "Creates a **unique index** on a field to ensure no duplicate values exist.\n\n- Enforces uniqueness at the database level.\n- Automatically prevents duplicate entries.\n- Typically used for **emails, usernames, and IDs**.\n\n**Example:**\n```atscript\n@mongo.index.unique \"uniqueEmailIndex\"\nemail: string.email\n```\n",
-			multiple: true,
-			nodeType: ["prop"],
-			argument: {
-				optional: true,
-				name: "indexName",
-				type: "string",
-				description: "The **name of the unique index** (optional). If omitted, property name is used."
-			}
-		}),
-		text: new AnnotationSpec({
-			description: "Creates a **legacy MongoDB text index** for full-text search.\n\n**⚠ WARNING:** *Text indexes slow down database operations. Use `@mongo.defineTextSearch` instead for better performance.*\n\n- Allows **basic full-text search** on a field.\n- Does **not support fuzzy matching or ranking**.\n- **Replaced by MongoDB Atlas Search Indexes (`@mongo.searchIndex.text`).**\n\n**Example:**\n```atscript\n@mongo.index.text 5\nbio: string\n```\n",
-			nodeType: ["prop"],
-			argument: {
-				optional: true,
-				name: "weight",
-				type: "number",
-				description: "Field importance in search results (higher = more relevant). Defaults to `1`."
-			}
-		})
-	},
+	index: { text: new AnnotationSpec({
+		description: "Creates a **legacy MongoDB text index** for full-text search with optional **weight** specification.\n\nUse this when you need per-field weight control. For simple full-text indexing without weights, use the generic `@db.index.fulltext` instead.\n\n**Example:**\n```atscript\n@db.mongo.index.text 5\nbio: string\n```\n",
+		nodeType: ["prop"],
+		argument: {
+			optional: true,
+			name: "weight",
+			type: "number",
+			description: "Field importance in search results (higher = more relevant). Defaults to `1`."
+		}
+	}) },
 	search: {
 		dynamic: new AnnotationSpec({
-			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
 			nodeType: ["interface"],
 			multiple: false,
 			argument: [{
@@ -127,7 +98,7 @@ const annotations = { mongo: {
 			}]
 		}),
 		static: new AnnotationSpec({
-			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@mongo.useTextSearch`** to be included in this search index.\n\n**Example:**\n```atscript\n@mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
 			nodeType: ["interface"],
 			multiple: true,
 			argument: [
@@ -148,12 +119,12 @@ const annotations = { mongo: {
 					optional: true,
 					name: "indexName",
 					type: "string",
-					description: "The name of the search index. Fields must reference this name using `@mongo.search.text`. If not set, defaults to `\"DEFAULT\"`."
+					description: "The name of the search index. Fields must reference this name using `@db.mongo.search.text`. If not set, defaults to `\"DEFAULT\"`."
 				}
 			]
 		}),
 		text: new AnnotationSpec({
-			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
 			nodeType: ["prop"],
 			multiple: true,
 			argument: [{
@@ -166,11 +137,11 @@ const annotations = { mongo: {
 				optional: true,
 				name: "indexName",
 				type: "string",
-				description: "The **name of the search index** defined in `@mongo.defineTextSearch`. This links the field to the correct index. If not set, defaults to `\"DEFAULT\"`."
+				description: "The **name of the search index** defined in `@db.mongo.search.static`. This links the field to the correct index. If not set, defaults to `\"DEFAULT\"`."
 			}]
 		}),
 		vector: new AnnotationSpec({
-			description: "Creates a **MongoDB Vector Search Index** for **semantic search, embeddings, and AI-powered search**.\n\n- Each field that stores vector embeddings **must define its own vector index**.\n- Supports **cosine similarity, Euclidean distance, and dot product similarity**.\n- Vector fields must be an **array of numbers**.\n\n**Example:**\n```atscript\n@mongo.search.vector 512, \"cosine\"\nembedding: mongo.vector\n```\n",
+			description: "Creates a **MongoDB Vector Search Index** for **semantic search, embeddings, and AI-powered search**.\n\n- Each field that stores vector embeddings **must define its own vector index**.\n- Supports **cosine similarity, Euclidean distance, and dot product similarity**.\n- Vector fields must be an **array of numbers**.\n\n**Example:**\n```atscript\n@db.mongo.search.vector 512, \"cosine\"\nembedding: mongo.vector\n```\n",
 			nodeType: ["prop"],
 			multiple: false,
 			argument: [
@@ -208,7 +179,7 @@ const annotations = { mongo: {
 			]
 		}),
 		filter: new AnnotationSpec({
-			description: "Assigns a field as a **filter field** for a **MongoDB Vector Search Index**.\n\n- The assigned field **must be indexed** for efficient filtering.\n- Filters allow vector search queries to return results **only within a specific category, user group, or tag**.\n- The vector index must be defined using `@mongo.search.vector`.\n\n**Example:**\n```atscript\n@mongo.search.vector 512, \"cosine\"\nembedding: number[]\n\n@mongo.search.filter \"embedding\"\ncategory: string\n```\n",
+			description: "Assigns a field as a **filter field** for a **MongoDB Vector Search Index**.\n\n- The assigned field **must be indexed** for efficient filtering.\n- Filters allow vector search queries to return results **only within a specific category, user group, or tag**.\n- The vector index must be defined using `@db.mongo.search.vector`.\n\n**Example:**\n```atscript\n@db.mongo.search.vector 512, \"cosine\"\nembedding: number[]\n\n@db.mongo.search.filter \"embedding\"\ncategory: string\n```\n",
 			nodeType: ["prop"],
 			multiple: true,
 			argument: [{
@@ -220,7 +191,7 @@ const annotations = { mongo: {
 		})
 	},
 	patch: { strategy: new AnnotationSpec({
-		description: "Defines the **patching strategy** for updating MongoDB documents.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@mongo.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
+		description: "Defines the **patching strategy** for updating MongoDB documents.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.mongo.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
 		nodeType: ["prop"],
 		multiple: false,
 		argument: {
@@ -240,7 +211,7 @@ const annotations = { mongo: {
 				if (!isStructure(def) && !isInterface(def) && !isArray(def)) wrongType = true;
 			} else if (!isStructure(definition) && !isInterface(definition) && !isArray(definition)) wrongType = true;
 			if (wrongType) errors.push({
-				message: `[mongo] type of object or array expected when using @mongo.patch.strategy`,
+				message: `[db.mongo] type of object or array expected when using @db.mongo.patch.strategy`,
 				severity: 1,
 				range: token.range
 			});
@@ -248,7 +219,7 @@ const annotations = { mongo: {
 		}
 	}) },
 	array: { uniqueItems: new AnnotationSpec({
-		description: "Marks an **array field** as containing *globally unique items* when handling **patch `$insert` operations**.\n\n- Forces the patcher to use **set-semantics** (`$setUnion`) instead of a plain append, so duplicates are silently skipped.\n- Has **no effect** on `$replace`, `$update`, or `$remove`.\n- If the array’s element type already defines one or more `@meta.isKey` properties, *uniqueness is implied* and this annotation is unnecessary (but harmless).\n\n**Example:**\n```atscript\n@mongo.array.uniqueItems\ntags: string[]\n\n// Later in a patch payload …\n{\n  $insert: {\n    tags: [\"mongo\", \"mongo\"] // second \"mongo\" is ignored\n  }\n}\n```\n",
+		description: "Marks an **array field** as containing *globally unique items* when handling **patch `$insert` operations**.\n\n- Forces the patcher to use **set-semantics** (`$setUnion`) instead of a plain append, so duplicates are silently skipped.\n- Has **no effect** on `$replace`, `$update`, or `$remove`.\n- If the array's element type already defines one or more `@expect.array.key` properties, *uniqueness is implied* and this annotation is unnecessary (but harmless).\n\n**Example:**\n```atscript\n@db.mongo.array.uniqueItems\ntags: string[]\n\n// Later in a patch payload …\n{\n  $insert: {\n    tags: [\"mongo\", \"mongo\"] // second \"mongo\" is ignored\n  }\n}\n```\n",
 		nodeType: ["prop"],
 		multiple: false,
 		validate(token, args, doc) {
@@ -262,14 +233,14 @@ const annotations = { mongo: {
 				if (!isArray(def)) wrongType = true;
 			} else if (!isArray(definition)) wrongType = true;
 			if (wrongType) errors.push({
-				message: `[mongo] type of array expected when using @mongo.array.uniqueItems`,
+				message: `[db.mongo] type of array expected when using @db.mongo.array.uniqueItems`,
 				severity: 1,
 				range: token.range
 			});
 			return errors;
 		}
 	}) }
-} };
+};
 
 //#endregion
 //#region packages/mongo/src/plugin/primitives.ts
@@ -277,7 +248,7 @@ const primitives = { mongo: { extensions: {
 	objectId: {
 		type: "string",
 		documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
-		expect: { pattern: /^[a-fA-F0-9]{24}$/ }
+		annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
 	},
 	vector: {
 		type: {
@@ -295,7 +266,7 @@ const MongoPlugin = () => ({
 	config() {
 		return {
 			primitives,
-			annotations
+			annotations: { db: { mongo: annotations } }
 		};
 	}
 });
@@ -306,7 +277,7 @@ const validateMongoIdPlugin = (ctx, def, value) => {
 	if (ctx.path === "_id" && def.type.tags.has("objectId")) return ctx.validateAnnotatedType(def, value instanceof ObjectId ? value.toString() : value);
 };
 const validateMongoUniqueArrayItemsPlugin = (ctx, def, value) => {
-	if (def.metadata.has("mongo.array.uniqueItems") && def.type.kind === "array") {
+	if (def.metadata.has("db.mongo.array.uniqueItems") && def.type.kind === "array") {
 		if (Array.isArray(value)) {
 			const separator = "▼↩";
 			const seen = new Set();
@@ -340,7 +311,7 @@ else obj[key] = value;
 }
 var CollectionPatcher = class CollectionPatcher {
 	/**
-	* Extract a set of *key properties* (annotated with `@meta.isKey`) from an
+	* Extract a set of *key properties* (annotated with `@expect.array.key`) from an
 	* array‐of‐objects type definition. These keys uniquely identify an element
 	* inside the array and are later used for `$update`, `$remove` and `$upsert`.
 	*
@@ -350,7 +321,7 @@ var CollectionPatcher = class CollectionPatcher {
 		if (def.type.of.type.kind === "object") {
 			const objType = def.type.of.type;
 			const keyProps = new Set();
-			for (const [key, val] of objType.props.entries()) if (val.metadata.get("meta.isKey")) keyProps.add(key);
+			for (const [key, val] of objType.props.entries()) if (val.metadata.get("expect.array.key")) keyProps.add(key);
 			return keyProps;
 		}
 		return new Set();
@@ -359,7 +330,7 @@ var CollectionPatcher = class CollectionPatcher {
 	* Build a runtime *Validator* that understands the extended patch payload.
 	*
 	*  * Adds per‑array *patch* wrappers (the `$replace`, `$insert`, … fields).
-	*  * Honors `mongo.patch.strategy === "merge"` metadata.
+	*  * Honors `db.mongo.patch.strategy === "merge"` metadata.
 	*
 	* @param collection Target collection wrapper
 	* @returns Atscript Validator
@@ -372,12 +343,12 @@ var CollectionPatcher = class CollectionPatcher {
 					for (const [prop, type] of def.type.props.entries()) obj.prop(prop, defineAnnotatedType().refTo(type).copyMetadata(type.metadata).optional(prop !== "_id").$type);
 					return obj.$type;
 				}
-				if (def.type.kind === "array" && collection.flatMap.get(path)?.metadata.get("mongo.__topLevelArray") && !def.metadata.has("mongo.__patchArrayValue")) {
+				if (def.type.kind === "array" && collection.flatMap.get(path)?.metadata.get("db.mongo.__topLevelArray") && !def.metadata.has("db.mongo.__patchArrayValue")) {
 					const defArray = def;
-					const mergeStrategy = defArray.metadata.get("mongo.patch.strategy") === "merge";
+					const mergeStrategy = defArray.metadata.get("db.mongo.patch.strategy") === "merge";
 					function getPatchType() {
 						const isPrimitive$1 = isAnnotatedTypeOfPrimitive(defArray.type.of);
-						if (isPrimitive$1) return defineAnnotatedType().refTo(def).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+						if (isPrimitive$1) return defineAnnotatedType().refTo(def).copyMetadata(def.metadata).annotate("db.mongo.__patchArrayValue").optional().$type;
 						if (defArray.type.of.type.kind === "object") {
 							const objType = defArray.type.of.type;
 							const t = defineAnnotatedType("object").copyMetadata(defArray.type.of.metadata);
@@ -385,17 +356,17 @@ var CollectionPatcher = class CollectionPatcher {
 							for (const [key, val] of objType.props.entries()) if (keyProps.size > 0) if (keyProps.has(key)) t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).$type);
 else t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).optional().$type);
 else t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).optional(!!val.optional).$type);
-							return defineAnnotatedType("array").of(t.$type).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+							return defineAnnotatedType("array").of(t.$type).copyMetadata(def.metadata).annotate("db.mongo.__patchArrayValue").optional().$type;
 						}
 						return undefined;
 					}
-					const fullType = defineAnnotatedType().refTo(def).copyMetadata(def.metadata).annotate("mongo.__patchArrayValue").optional().$type;
+					const fullType = defineAnnotatedType().refTo(def).copyMetadata(def.metadata).annotate("db.mongo.__patchArrayValue").optional().$type;
 					const patchType = getPatchType();
 					return patchType ? defineAnnotatedType("object").prop("$replace", fullType).prop("$insert", fullType).prop("$upsert", fullType).prop("$update", mergeStrategy ? patchType : fullType).prop("$remove", patchType).optional().$type : defineAnnotatedType("object").prop("$replace", fullType).prop("$insert", fullType).optional().$type;
 				}
 				return def;
 			},
-			partial: (def, path) => path !== "" && def.metadata.get("mongo.patch.strategy") === "merge"
+			partial: (def, path) => path !== "" && def.metadata.get("db.mongo.patch.strategy") === "merge"
 		});
 	}
 	/**
@@ -446,9 +417,9 @@ else t.prop(key, defineAnnotatedType().refTo(val).copyMetadata(def.metadata).opt
 		for (const [_key, value] of Object.entries(payload)) {
 			const key = evalKey(_key);
 			const flatType = this.collection.flatMap.get(key);
-			const topLevelArray = flatType?.metadata?.get("mongo.__topLevelArray");
+			const topLevelArray = flatType?.metadata?.get("db.mongo.__topLevelArray");
 			if (typeof value === "object" && topLevelArray) this.parseArrayPatch(key, value);
-else if (typeof value === "object" && this.collection.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge") this.flattenPayload(value, key);
+else if (typeof value === "object" && this.collection.flatMap.get(key)?.metadata?.get("db.mongo.patch.strategy") === "merge") this.flattenPayload(value, key);
 else if (key !== "_id") this._set(key, value);
 		}
 		return this.updatePipeline;
@@ -502,7 +473,7 @@ else if (key !== "_id") this._set(key, value);
 	* - unique / keyed    → delegate to _upsert (insert-or-update)
 	*/ _insert(key, input, keyProps) {
 		if (!input?.length) return;
-		const uniqueItems = this.collection.flatMap.get(key)?.metadata?.has("mongo.array.uniqueItems");
+		const uniqueItems = this.collection.flatMap.get(key)?.metadata?.has("db.mongo.array.uniqueItems");
 		if (uniqueItems || keyProps.size > 0) this._upsert(key, input, keyProps);
 else this._set(key, { $concatArrays: [{ $ifNull: [`$${key}`, []] }, input] });
 	}
@@ -540,7 +511,7 @@ else this._set(key, { $concatArrays: [{ $ifNull: [`$${key}`, []] }, input] });
 	*/ _update(key, input, keyProps) {
 		if (!input?.length) return;
 		if (keyProps.size > 0) {
-			const mergeStrategy = this.collection.flatMap.get(key)?.metadata?.get("mongo.patch.strategy") === "merge";
+			const mergeStrategy = this.collection.flatMap.get(key)?.metadata?.get("db.mongo.patch.strategy") === "merge";
 			const keys = [...keyProps];
 			this._set(key, { $reduce: {
 				input,
@@ -749,13 +720,13 @@ else {
 	}
 	_prepareIndexesForCollection() {
 		const typeMeta = this.type.metadata;
-		const dynamicText = typeMeta.get("mongo.search.dynamic");
+		const dynamicText = typeMeta.get("db.mongo.search.dynamic");
 		if (dynamicText) this._setSearchIndex("dynamic_text", "_", {
 			mappings: { dynamic: true },
 			analyzer: dynamicText.analyzer,
 			text: { fuzzy: { maxEdits: dynamicText.fuzzy || 0 } }
 		});
-		for (const textSearch of typeMeta.get("mongo.search.static") || []) this._setSearchIndex("search_text", textSearch.indexName, {
+		for (const textSearch of typeMeta.get("db.mongo.search.static") || []) this._setSearchIndex("search_text", textSearch.indexName, {
 			mappings: { fields: {} },
 			analyzer: textSearch.analyzer,
 			text: { fuzzy: { maxEdits: textSearch.fuzzy || 0 } }
@@ -778,25 +749,35 @@ else {
 		}
 	}
 	_prepareIndexesForField(fieldName, metadata) {
-		for (const index of metadata.get("mongo.index.plain") || []) this._addIndexField("plain", index === true ? fieldName : index, fieldName);
-		for (const index of metadata.get("mongo.index.unique") || []) this._addIndexField("unique", index === true ? fieldName : index, fieldName);
-		const textWeight = metadata.get("mongo.index.text");
+		for (const index of metadata.get("db.index.plain") || []) {
+			const name = index === true ? fieldName : index.name || fieldName;
+			this._addIndexField("plain", name, fieldName);
+		}
+		for (const index of metadata.get("db.index.unique") || []) {
+			const name = index === true ? fieldName : index.name || fieldName;
+			this._addIndexField("unique", name, fieldName);
+		}
+		for (const index of metadata.get("db.index.fulltext") || []) {
+			const name = index === true ? "" : index.name || "";
+			this._addIndexField("text", name, fieldName, 1);
+		}
+		const textWeight = metadata.get("db.mongo.index.text");
 		if (textWeight) this._addIndexField("text", "", fieldName, textWeight === true ? 1 : textWeight);
-		for (const index of metadata.get("mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, fieldName, index.analyzer);
-		const vectorIndex = metadata.get("mongo.search.vector");
+		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, fieldName, index.analyzer);
+		const vectorIndex = metadata.get("db.mongo.search.vector");
 		if (vectorIndex) this._setSearchIndex("vector", vectorIndex.indexName || fieldName, { fields: [{
 			type: "vector",
 			path: fieldName,
 			similarity: vectorIndex.similarity || "dotProduct",
 			numDimensions: vectorIndex.dimensions
 		}] });
-		for (const index of metadata.get("mongo.search.filter") || []) this._vectorFilters.set(indexKey("vector", index.indexName), fieldName);
+		for (const index of metadata.get("db.mongo.search.filter") || []) this._vectorFilters.set(indexKey("vector", index.indexName), fieldName);
 	}
 	_flatten() {
 		if (!this._flatMap) {
 			this._prepareIndexesForCollection();
 			this._flatMap = flattenAnnotatedType(this.type, {
-				topLevelArrayTag: "mongo.__topLevelArray",
+				topLevelArrayTag: "db.mongo.__topLevelArray",
 				excludePhantomTypes: true,
 				onField: (path, _type, metadata) => this._prepareIndexesForField(path, metadata)
 			});
@@ -1008,8 +989,8 @@ else if (this.idType !== "objectId") throw new Error("Missing \"_id\" field");
 		this._vectorFilters = new Map();
 		this._uniqueProps = new Set();
 		if (!isAnnotatedType(_type)) throw new Error("Atscript Annotated Type expected");
-		const name = _type.metadata.get("mongo.collection");
-		if (!name) throw new Error("@mongo.collection annotation expected with collection name");
+		const name = _type.metadata.get("db.table");
+		if (!name) throw new Error("@db.table annotation expected with collection name");
 		if (_type.type.kind !== "object") throw new Error("Mongo collection must be an object type");
 		this.name = name;
 		this.collection = asMongo.db.collection(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/mongo",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -19,9 +19,14 @@
     "directory": "packages/mongo"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "type": "module",
+  "bin": {
+    "atscript-mongo-skill": "./scripts/setup-skills.js"
+  },
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
@@ -37,11 +42,12 @@
   },
   "peerDependencies": {
     "mongodb": "^6.17.0",
-    "@atscript/core": "^0.1.27",
-    "@atscript/typescript": "^0.1.27"
+    "@atscript/core": "^0.1.28",
+    "@atscript/typescript": "^0.1.28"
   },
   "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,78 @@
+#!/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-mongo'
+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) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  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 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.')
+} 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-mongo/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: atscript-mongo
+description: Use this skill when working with @atscript/mongo — to define MongoDB collections with @db.table and @db.mongo.collection, create indexes with @db.index.plain/@db.index.unique/@db.mongo.index.text, configure Atlas Search with @db.mongo.search.*, control patch strategies with @db.mongo.patch.strategy, use AsCollection for CRUD operations (insert/replace/update/syncIndexes), validate data with createValidator, or configure MongoPlugin in atscript.config.
+---
+
+# @atscript/mongo
+
+MongoDB metadata extension for Atscript. Defines annotations for collections, indexes, search, and patch strategies, plus runtime classes (`AsCollection`, `AsMongo`) with built-in validation, filtering, querying, and writing.
+
+## 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... |
+|--------|------|-------------|
+| Core setup & plugin config | [core.md](core.md) | Installing the plugin, configuring atscript.config, understanding the plugin architecture |
+| Annotations reference | [annotations.md](annotations.md) | Writing .as files with database and MongoDB annotations, understanding annotation arguments |
+| Collections & CRUD | [collections.md](collections.md) | Using AsCollection/AsMongo for insert, replace, update, query, or sync indexes |
+| Patch strategies | [patches.md](patches.md) | Working with @db.mongo.patch.strategy, array patch operations ($insert/$upsert/$update/$remove/$replace) |
+
+## Quick reference
+
+```atscript
+@db.table 'users'
+@db.mongo.collection
+export interface User {
+    @db.index.unique 'email_idx'
+    email: string.email
+
+    @db.mongo.index.text 5
+    name: string
+
+    @db.index.plain 'status_idx'
+    isActive: boolean
+}
+```
+
+```typescript
+import { AsMongo } from '@atscript/mongo'
+import { User } from './user.as'
+
+const asMongo = new AsMongo('mongodb://localhost:27017/mydb')
+const users = asMongo.getCollection(User)
+await users.insert({ email: 'a@b.com', name: 'Alice', isActive: true })
+```