@atscript/moost-mongo 0.1.27 → 0.1.28

package/dist/index.cjs

@@ -30,7 +30,7 @@ const __atscript_mongo = __toESM(require("@atscript/mongo"));
 
 //#region packages/moost-mongo/src/decorators.ts
 const COLLECTION_DEF = "__atscript_mongo_collection_def";
-const CollectionController = (type, prefix) => (0, moost.ApplyDecorators)((0, moost.Provide)(COLLECTION_DEF, () => type), (0, moost.Controller)(prefix || type.metadata.get("mongo.collection") || type.name), (0, moost.Inherit)());
+const CollectionController = (type, prefix) => (0, moost.ApplyDecorators)((0, moost.Provide)(COLLECTION_DEF, () => type), (0, moost.Controller)(prefix || type.metadata.get("db.table") || type.name), (0, moost.Inherit)());
 const InjectCollection = (type) => (0, moost.Resolve)(async ({ instantiate }) => {
 	const asMongo = await instantiate(__atscript_mongo.AsMongo);
 	return asMongo.getCollection(type);
@@ -93,7 +93,7 @@ _define_property$1(SelectControlDto, "__is_atscript_annotated_type", true);
 _define_property$1(SelectControlDto, "type", {});
 _define_property$1(SelectControlDto, "metadata", new Map());
 _define_property$1(SelectControlDto, "id", "SelectControlDto");
-(0, __atscript_typescript_utils.defineAnnotatedType)("object", QueryControlsDto).prop("$skip", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.min", { minValue: 0 }).annotate("expect.int", true).optional().$type).prop("$limit", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.min", { minValue: 0 }).annotate("expect.int", true).optional().$type).prop("$count", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type).prop("$sort", (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).optional().$type).prop("$search", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type);
+(0, __atscript_typescript_utils.defineAnnotatedType)("object", QueryControlsDto).prop("$skip", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("boolean").tags("boolean").optional().$type).prop("$sort", (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SortControlDto).optional().$type).prop("$select", (0, __atscript_typescript_utils.defineAnnotatedType)().refTo(SelectControlDto).optional().$type).prop("$search", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type).prop("$index", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").optional().$type);
 (0, __atscript_typescript_utils.defineAnnotatedType)("object", PagesControlsDto).prop("$page", (0, __atscript_typescript_utils.defineAnnotatedType)().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
 	flags: "u",
@@ -144,7 +144,7 @@ var AsMongoController = class {
 	* Override to seed data, register change streams, etc. Both sync and async
 	* return types are supported.
 	*/ init() {
-		if (this.type.metadata.get("mongo.autoIndexes") === false) {} else return this.asCollection.syncIndexes();
+		if (this.type.metadata.get("db.mongo.autoIndexes") === false) {} else return this.asCollection.syncIndexes();
 	}
 	/** Returns (and memoises) validator for *query* endpoint controls. */ get queryControlsValidator() {
 		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
@@ -468,7 +468,7 @@ else return new __moostjs_event_http.HttpError(500, "Not saved");
 		_define_property(this, "_getOneControlsValidator", void 0);
 		this.asMongo = asMongo;
 		this.type = type;
-		this.logger = app.getLogger(`mongo [${type.metadata.get("mongo.collection") || ""}]`);
+		this.logger = app.getLogger(`mongo [${type.metadata.get("db.table") || ""}]`);
 		this.asCollection = this.asMongo.getCollection(type, this.logger);
 		this.logger.info(`Initializing Collection`);
 		try {

package/dist/index.d.ts

@@ -57,11 +57,11 @@ declare class AsMongoController<T extends TAtscriptAnnotatedType = TAtscriptAnno
     private _pagesControlsValidator?;
     private _getOneControlsValidator?;
     /** Returns (and memoises) validator for *query* endpoint controls. */
-    protected get queryControlsValidator(): Validator<any, unknown> | undefined;
+    protected get queryControlsValidator(): Validator<any, unknown>;
     /** Returns (and memoises) validator for *pages* endpoint controls. */
-    protected get pagesControlsValidator(): Validator<any, unknown> | undefined;
+    protected get pagesControlsValidator(): Validator<any, unknown>;
     /** Returns (and memoises) validator for *one* endpoint controls. */
-    protected get getOneControlsValidator(): Validator<any, unknown> | undefined;
+    protected get getOneControlsValidator(): Validator<any, unknown>;
     /**
      * Validates `$limit`, `$skip`, `$sort`, `$select`, `$count` controls for the
      * **query** endpoint.
@@ -241,7 +241,7 @@ declare const COLLECTION_DEF = "__atscript_mongo_collection_def";
 /**
  * Combines the boilerplate needed to turn an {@link AsMongoController}
  * subclass into a fully wired HTTP controller for a given
- * **@mongo.collection** model.
+ * **@db.table** model.
  *
  * Internally applies three decorators:
  * 1. **Provide** – registers the collection constructor under {@link COLLECTION_DEF}.
@@ -250,9 +250,9 @@ declare const COLLECTION_DEF = "__atscript_mongo_collection_def";
  * 3. **Inherit** – copies metadata (routes, guards, etc.) from the
  *    parent class so they stay active in the derived controller.
  *
- * @param type   AtScript-annotated constructor produced by `@mongo.collection`.
+ * @param type   AtScript-annotated constructor produced by `@db.table`.
  * @param prefix Optional route prefix. Defaults to
- *               `type.metadata.get("mongo.collection")` or the class name.
+ *               `type.metadata.get("db.table")` or the class name.
  *
  * @example
  * ```ts
@@ -271,7 +271,7 @@ declare const CollectionController: (type: TAtscriptAnnotatedType & {
  * > (e.g. `@Provide(AsMongo, () => new AsMongo(url))`).
  *
  * @param type AtScript-annotated constructor produced by
- *             `@mongo.collection`.
+ *             `@db.table`.
  *
  * @example
  * ```ts

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { AsMongo as AsMongo$1 } from "@atscript/mongo";
 
 //#region packages/moost-mongo/src/decorators.ts
 const COLLECTION_DEF = "__atscript_mongo_collection_def";
-const CollectionController = (type, prefix) => ApplyDecorators(Provide(COLLECTION_DEF, () => type), Controller(prefix || type.metadata.get("mongo.collection") || type.name), Inherit());
+const CollectionController = (type, prefix) => ApplyDecorators(Provide(COLLECTION_DEF, () => type), Controller(prefix || type.metadata.get("db.table") || type.name), Inherit());
 const InjectCollection = (type) => Resolve(async ({ instantiate }) => {
 	const asMongo = await instantiate(AsMongo$1);
 	return asMongo.getCollection(type);
@@ -69,7 +69,7 @@ _define_property$1(SelectControlDto, "__is_atscript_annotated_type", true);
 _define_property$1(SelectControlDto, "type", {});
 _define_property$1(SelectControlDto, "metadata", new Map());
 _define_property$1(SelectControlDto, "id", "SelectControlDto");
-defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.min", { minValue: 0 }).annotate("expect.int", true).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.min", { minValue: 0 }).annotate("expect.int", true).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType().refTo(SelectControlDto).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type);
+defineAnnotatedType("object", QueryControlsDto).prop("$skip", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$limit", defineAnnotatedType().designType("number").tags("positive", "int", "number").annotate("expect.int", true).annotate("expect.min", { minValue: 0 }).optional().$type).prop("$count", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("$sort", defineAnnotatedType().refTo(SortControlDto).optional().$type).prop("$select", defineAnnotatedType().refTo(SelectControlDto).optional().$type).prop("$search", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("$index", defineAnnotatedType().designType("string").tags("string").optional().$type);
 defineAnnotatedType("object", PagesControlsDto).prop("$page", defineAnnotatedType().designType("string").tags("string").annotate("expect.pattern", {
 	pattern: "^\\d+$",
 	flags: "u",
@@ -120,7 +120,7 @@ var AsMongoController = class {
 	* Override to seed data, register change streams, etc. Both sync and async
 	* return types are supported.
 	*/ init() {
-		if (this.type.metadata.get("mongo.autoIndexes") === false) {} else return this.asCollection.syncIndexes();
+		if (this.type.metadata.get("db.mongo.autoIndexes") === false) {} else return this.asCollection.syncIndexes();
 	}
 	/** Returns (and memoises) validator for *query* endpoint controls. */ get queryControlsValidator() {
 		if (!this._queryControlsValidator) this._queryControlsValidator = QueryControlsDto.validator();
@@ -444,7 +444,7 @@ else return new HttpError(500, "Not saved");
 		_define_property(this, "_getOneControlsValidator", void 0);
 		this.asMongo = asMongo;
 		this.type = type;
-		this.logger = app.getLogger(`mongo [${type.metadata.get("mongo.collection") || ""}]`);
+		this.logger = app.getLogger(`mongo [${type.metadata.get("db.table") || ""}]`);
 		this.asCollection = this.asMongo.getCollection(type, this.logger);
 		this.logger.info(`Initializing Collection`);
 		try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-mongo",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Atscript Mongo for Moost.",
   "keywords": [
     "annotations",
@@ -20,8 +20,13 @@
     "url": "git+https://github.com/moostjs/atscript.git",
     "directory": "packages/moost-mongo"
   },
+  "bin": {
+    "atscript-moost-mongo-skill": "./scripts/setup-skills.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -38,22 +43,23 @@
     "urlql": "^0.0.5"
   },
   "devDependencies": {
-    "@moostjs/event-http": "^0.6.0",
+    "@moostjs/event-http": "^0.6.2",
     "mongodb": "^6.17.0",
-    "moost": "^0.6.0",
+    "moost": "^0.6.2",
     "vitest": "3.2.4",
-    "@atscript/core": "^0.1.27"
+    "@atscript/core": "^0.1.28"
   },
   "peerDependencies": {
-    "@moostjs/event-http": "^0.6.0",
+    "@moostjs/event-http": "^0.6.2",
     "mongodb": "^6.17.0",
-    "moost": "^0.6.0",
-    "@atscript/mongo": "^0.1.27",
-    "@atscript/typescript": "^0.1.27"
+    "moost": "^0.6.2",
+    "@atscript/mongo": "^0.1.28",
+    "@atscript/typescript": "^0.1.28"
   },
   "scripts": {
     "pub": "pnpm publish --access public",
     "before-build": "node ../typescript/cli.cjs -f js",
-    "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-moost-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-moost-mongo/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: atscript-moost-mongo
+description: Use this skill when working with @atscript/moost-mongo — to create REST controllers for MongoDB collections with AsMongoController, use CollectionController decorator, inject collections with InjectCollection, configure query/pagination/sorting with URLQL DTOs, override controller hooks (onWrite/onRemove/transformFilter/prepareSearch), or integrate @atscript/mongo collections into a Moost application.
+---
+
+# @atscript/moost-mongo
+
+Moost framework integration for Atscript MongoDB. Provides automated REST controllers for MongoDB collections defined via `.as` types, with full validation, pagination, and search support.
+
+## 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 & architecture | [core.md](core.md) | Installing, configuring, understanding controller architecture |
+| Controllers & hooks | [controllers.md](controllers.md) | Creating controllers, overriding hooks, customizing CRUD behavior |
+| Decorators & DI | [decorators.md](decorators.md) | Using CollectionController, InjectCollection, understanding DI wiring |
+
+## Quick reference
+
+```typescript
+import { AsMongoController, CollectionController } from '@atscript/moost-mongo'
+import { AsMongo } from '@atscript/mongo'
+import { Provide } from 'moost'
+import { User } from './user.as'
+
+@Provide(AsMongo, () => new AsMongo('mongodb://localhost:27017/mydb'))
+@CollectionController(User)
+export class UsersController extends AsMongoController<typeof User> {}
+// That's it — GET/POST/PUT/PATCH/DELETE endpoints are all automatic
+```

package/skills/atscript-moost-mongo/controllers.md

@@ -0,0 +1,138 @@
+# Controllers & Hooks — @atscript/moost-mongo
+
+> Creating REST controllers and customizing behavior via hooks.
+
+## Basic Controller
+
+The simplest controller is an empty subclass:
+
+```typescript
+import { AsMongoController, CollectionController } from '@atscript/moost-mongo'
+import { AsMongo } from '@atscript/mongo'
+import { Provide } from 'moost'
+import { User } from './user.as'
+
+@Provide(AsMongo, () => new AsMongo(process.env.MONGO_URI!))
+@CollectionController(User)
+export class UsersController extends AsMongoController<typeof User> {}
+```
+
+This gives you all 7 REST endpoints automatically.
+
+## Overridable Hooks
+
+### `init()`
+
+Called during controller initialization. Use for one-time setup like syncing indexes:
+
+```typescript
+@CollectionController(User)
+export class UsersController extends AsMongoController<typeof User> {
+  async init() {
+    await this.collection.syncIndexes()
+  }
+}
+```
+
+### `onWrite(action, data, opts)`
+
+Intercepts write operations. `action` is `'insert'`, `'replace'`, or `'update'`.
+
+```typescript
+async onWrite(action: string, data: any, opts: any) {
+  if (action === 'insert') {
+    data.createdAt = new Date().toISOString()
+  }
+  data.updatedAt = new Date().toISOString()
+  return super.onWrite(action, data, opts)
+}
+```
+
+### `onRemove(id, opts)`
+
+Intercepts delete operations. Return the result or throw to prevent deletion.
+
+```typescript
+async onRemove(id: string, opts: any) {
+  // Soft delete instead
+  await this.collection.update({ _id: id, deletedAt: new Date().toISOString() })
+  return { deletedCount: 1 }
+}
+```
+
+### `transformFilter(filter)`
+
+Modify the MongoDB filter before any query. Use for multi-tenancy, soft deletes, etc.
+
+```typescript
+transformFilter(filter: Filter<any>) {
+  return { ...filter, tenantId: this.currentTenantId }
+}
+```
+
+### `transformProjection(projection)`
+
+Modify field projection before queries.
+
+### `prepareSearch(query, index?)`
+
+Override to customize how text/vector search queries are built.
+
+### `prepareTextSearch(query, index?)`
+
+Override for text search customization.
+
+### `prepareVectorSearch(query, index?)`
+
+Override for vector search customization.
+
+## Query Controls
+
+The GET endpoints accept URLQL query parameters:
+
+### `/query` endpoint
+
+Uses `QueryControlsDto`:
+- `$skip` — Number of documents to skip
+- `$limit` — Maximum documents to return
+- `$count` — If true, return count instead of documents
+- `$sort` — Sort specification (e.g. `$sort[name]=1`)
+- `$select` — Field projection (e.g. `$select[name]=1`)
+- `$search` — Text search query
+- `$index` — Search index name
+
+### `/pages` endpoint
+
+Uses `PagesControlsDto`:
+- `$page` — Page number (1-based)
+- `$size` — Page size
+- `$sort`, `$select`, `$search`, `$index` — Same as query
+
+### `/one/:id` endpoint
+
+Uses `GetOneControlsDto`:
+- `$select` — Field projection
+- `:id` — Tries `_id` first, then falls back to `@db.index.unique` fields
+
+## Custom Route Prefix
+
+```typescript
+@CollectionController(User, 'api/v2/users')
+export class UsersV2Controller extends AsMongoController<typeof User> {}
+```
+
+If not specified, defaults to the `@db.table` name.
+
+## Accessing the Collection
+
+Inside controller methods, use `this.collection` to access the underlying `AsCollection`:
+
+```typescript
+@CollectionController(User)
+export class UsersController extends AsMongoController<typeof User> {
+  async customMethod() {
+    const users = await this.collection.collection.find({ isActive: true }).toArray()
+    return users
+  }
+}
+```

package/skills/atscript-moost-mongo/core.md

@@ -0,0 +1,62 @@
+# Core Setup — @atscript/moost-mongo
+
+> Installation, configuration, and architecture overview.
+
+## Installation
+
+```bash
+npm install @atscript/moost-mongo
+# peer dependencies:
+npm install @atscript/mongo @atscript/typescript moost @moostjs/event-http mongodb
+```
+
+## Configuration
+
+Add both `ts()` and `MongoPlugin()` to your `atscript.config.ts`:
+
+```typescript
+import { defineConfig } from '@atscript/core'
+import { ts } from '@atscript/typescript'
+import { MongoPlugin } from '@atscript/mongo'
+
+export default defineConfig({
+  rootDir: 'src',
+  plugins: [ts(), MongoPlugin()],
+})
+```
+
+## Architecture
+
+The package provides three main exports:
+
+- **`AsMongoController<T>`** — Generic base class with all CRUD endpoints
+- **`CollectionController(type, prefix?)`** — Class decorator combining `@Provide`, `@Controller`, `@Inherit`
+- **`InjectCollection(type)`** — Parameter decorator for DI injection of `AsCollection<T>`
+
+### REST Endpoints (automatic)
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/<prefix>/query` | GET | List with URLQL filtering/sorting |
+| `/<prefix>/pages` | GET | Paginated list |
+| `/<prefix>/one/:id` | GET | Single doc by `_id` or unique field |
+| `/<prefix>` | POST | Insert one or many |
+| `/<prefix>` | PUT | Replace by `_id` |
+| `/<prefix>` | PATCH | Partial update by `_id` |
+| `/<prefix>/:id` | DELETE | Remove by `_id` |
+
+The route prefix defaults to the `@db.table` name but can be overridden in `CollectionController`.
+
+## Regenerating atscript.d.ts
+
+After annotation changes:
+
+```bash
+cd packages/moost-mongo && node ../typescript/dist/cli.cjs -f dts
+```
+
+## Best Practices
+
+- Use `@CollectionController(Type)` on an empty subclass for zero-config CRUD
+- Override hooks (`onWrite`, `onRemove`, `transformFilter`) for custom business logic
+- Provide `AsMongo` at the controller level via `@Provide(AsMongo, () => new AsMongo(url))`

package/skills/atscript-moost-mongo/decorators.md

@@ -0,0 +1,88 @@
+# Decorators & DI — @atscript/moost-mongo
+
+> Using CollectionController, InjectCollection, and understanding DI wiring.
+
+## `CollectionController(type, prefix?)`
+
+Class decorator that combines three Moost decorators:
+
+1. **`@Provide(COLLECTION_DEF, () => type)`** — Registers the Atscript annotated type in DI
+2. **`@Controller(prefix)`** — Registers the class as a Moost HTTP controller
+3. **`@Inherit()`** — Copies metadata (routes, guards) from the parent class
+
+```typescript
+import { CollectionController } from '@atscript/moost-mongo'
+import { User } from './user.as'
+
+@CollectionController(User)           // prefix defaults to @db.table name ("users")
+@CollectionController(User, 'people') // explicit prefix
+```
+
+### Parameters
+
+- **`type`** — Atscript annotated constructor from a `.as` import
+- **`prefix?`** — Optional route prefix. Defaults to `type.metadata.get('db.table')` or `type.name`
+
+## `InjectCollection(type)`
+
+Parameter decorator that injects a lazily-resolved `AsCollection` instance. Use in any DI-managed class, not just controllers.
+
+```typescript
+import { InjectCollection } from '@atscript/moost-mongo'
+import { AsCollection } from '@atscript/mongo'
+import { Injectable } from 'moost'
+import { User } from './user.as'
+
+@Injectable()
+export class UserService {
+  constructor(
+    @InjectCollection(User)
+    private users: AsCollection<typeof User>
+  ) {}
+
+  async findActiveUsers() {
+    return this.users.collection.find({ isActive: true }).toArray()
+  }
+}
+```
+
+### Requirements
+
+`AsMongo` must be provided in the current DI scope:
+
+```typescript
+@Provide(AsMongo, () => new AsMongo(connectionString))
+```
+
+## DI Wiring Pattern
+
+The typical setup:
+
+```typescript
+import { AsMongo } from '@atscript/mongo'
+import { AsMongoController, CollectionController } from '@atscript/moost-mongo'
+import { Provide } from 'moost'
+import { User } from './user.as'
+import { Product } from './product.as'
+
+// Provide AsMongo at the module/app level
+@Provide(AsMongo, () => new AsMongo(process.env.MONGO_URI!))
+class AppModule {}
+
+// Each controller gets its own collection automatically
+@CollectionController(User)
+export class UsersController extends AsMongoController<typeof User> {}
+
+@CollectionController(Product)
+export class ProductsController extends AsMongoController<typeof Product> {}
+```
+
+## COLLECTION_DEF Token
+
+The DI token under which the Atscript annotated type is registered:
+
+```typescript
+import { COLLECTION_DEF } from '@atscript/moost-mongo'
+```
+
+This is used internally by `AsMongoController` to resolve the collection type. You typically don't need to use it directly.