@joktec/skills 0.1.7 → 0.1.8

package/dist/claude/skills/joktec-mysql-skill/SKILL.md

@@ -22,6 +22,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 

package/dist/claude/skills/joktec-mysql-skill/references/entities.md

@@ -47,6 +47,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -85,12 +86,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:

package/dist/codex/skills/joktec-mysql-skill/SKILL.md

@@ -22,6 +22,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 

package/dist/codex/skills/joktec-mysql-skill/references/entities.md

@@ -47,6 +47,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -85,12 +86,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:

package/dist/copilot/.github/copilot-instructions.md

@@ -450,6 +450,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 
@@ -511,6 +512,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -549,12 +551,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:

package/dist/cursor/.cursor/rules/joktec-mysql-skill.mdc

@@ -19,6 +19,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 
@@ -80,6 +81,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -118,12 +120,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:

package/dist/gemini/GEMINI.md

@@ -458,6 +458,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 
@@ -519,6 +520,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -557,12 +559,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:

package/dist/windsurf/.windsurf/rules/joktec-mysql-skill.md

@@ -15,6 +15,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 
@@ -76,6 +77,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -114,12 +116,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joktec/skills",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "private": false,
   "description": "Hybrid agent skill pack for using @joktec/* libraries in consumer projects.",
   "license": "MIT",

package/skill-pack.json

@@ -1,6 +1,6 @@
 {
   "name": "@joktec/skills",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "sourceOfTruth": "../joktec-framework",
   "frameworkBaseline": {
     "repo": "https://github.com/joktec/joktec-framework",

package/skills/joktec-mysql-skill/SKILL.md

@@ -22,6 +22,7 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
 - Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
 - Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
 - Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
 - For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 

package/skills/joktec-mysql-skill/references/entities.md

@@ -47,6 +47,7 @@ Wrapper philosophy:
 
 - prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
 - use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
 - use raw TypeORM only for advanced cases that the wrapper does not model cleanly
 - keep storage write behavior and API documentation behavior distinct when needed
 
@@ -85,12 +86,32 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
 | `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
 | `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
 | `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
 | Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
 
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
 ## Read-Only Metadata
 
 `immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate: