@joktec/skills 0.1.4 → 0.1.7

package/skills/advanced-typescript-design/references/simple.md

@@ -0,0 +1,149 @@
+# Simple TypeScript Design Guidance
+
+Use this reference for ordinary application and library work where readability, stable APIs, and maintainable TypeScript matter more than type-level cleverness.
+
+## Default Practices
+
+- Prefer explicit, small interfaces for public boundaries and concrete classes for runtime behavior with lifecycle, dependency injection, or decorators.
+- Use `type` for unions, mapped shapes, conditional aliases, and composition. Use `interface` for object contracts intended to be implemented or extended.
+- Keep primitive aliases meaningful. A `UserId` alias can clarify intent, but it does not add runtime safety unless paired with validation or branding.
+- Model data with plain objects when behavior is absent. Add classes when construction, methods, inheritance hooks, decorators, or framework reflection are required.
+- Keep DTOs, entities, requests, and responses separate when they have different validation, persistence, or transport concerns.
+- Avoid `any` at public boundaries. Use `unknown` for untrusted data, then narrow or validate it.
+- Prefer narrow generic constraints such as `T extends Entity` over unconstrained `T` when the implementation depends on object semantics.
+
+## Classes, Interfaces, and OOP
+
+- Use abstract classes for shared runtime behavior, protected hooks, and constructor-injected dependencies.
+- Use interfaces for contracts that should not carry runtime behavior.
+- Prefer composition over inheritance when variants differ by collaborator rather than lifecycle.
+- Keep protected hooks purposeful: `afterInit`, `transform`, `validate`, and `map` are good when subclasses are expected to customize one stable step.
+- Avoid deep inheritance chains. If a third level appears, consider Strategy, Adapter, or composition.
+
+## Common Data Structures
+
+- Use `Record<K, V>` when the key set is known or constrained.
+- Use `{ [key: string]: V }` when the object is truly open-ended.
+- Use `Map<K, V>` when keys are not strings, insertion order matters, or frequent add/remove operations are central.
+- Use arrays for ordered collections and tuples for fixed positional contracts.
+- Use discriminated unions for state or command variants instead of loose booleans.
+- Keep hash-like caches private unless callers need iteration, eviction, or explicit lifecycle.
+
+## Basic Types and Utilities
+
+- Use union literals for finite options: status, mode, operation, direction.
+- Use `Pick`, `Omit`, `Partial`, `Required`, `Readonly`, `Record`, `Extract`, and `Exclude` before writing custom utilities.
+- Use `keyof` and indexed access types for property-safe APIs.
+- Use overloads sparingly; prefer a single options object when overloads become hard to read.
+- Keep mapped types shallow unless the data is truly nested and the API benefits from deep transformation.
+
+## Simple Decorators
+
+- Use decorator factories to attach framework metadata or compose existing decorators.
+- Keep decorator options serializable and explicit where possible.
+- Separate metadata collection from runtime execution. A decorator should usually register intent; a loader/service should execute it later.
+- Avoid parsing function source in ordinary decorators. If runtime argument-name mapping truly requires it, escalate to `advanced.md` and isolate the parser behind tests.
+- Test decorators at the behavior boundary, not only by checking metadata keys.
+
+## Pattern Choices
+
+- Use Factory Method or simple factory functions when object creation varies by type or config.
+- Use Builder for stepwise configuration only when partially built objects are common or order matters.
+- Use Adapter to normalize third-party APIs behind project interfaces.
+- Use Facade to simplify a noisy subsystem for callers.
+- Use Decorator when behavior should wrap a method/object without changing its public contract.
+- Use Template Method when a base class owns an algorithm and subclasses fill in specific steps.
+- Use Strategy when an algorithm family changes independently from the caller.
+- Use Observer or Mediator for event-style communication, but keep ownership and error handling explicit.
+
+## Symbolic Examples
+
+Use examples like these to reason about shape and tradeoffs. Keep final code adapted to the repository style.
+
+### Strategy with a Narrow Interface
+
+```typescript
+interface PriceStrategy {
+  total(items: CartItem[]): number;
+}
+
+class RetailPrice implements PriceStrategy {
+  total(items: CartItem[]) {
+    return items.reduce((sum, item) => sum + item.price, 0);
+  }
+}
+
+class WholesalePrice implements PriceStrategy {
+  total(items: CartItem[]) {
+    return items.reduce((sum, item) => sum + item.price * 0.9, 0);
+  }
+}
+
+class CheckoutService {
+  constructor(private readonly strategy: PriceStrategy) {}
+
+  quote(items: CartItem[]) {
+    return this.strategy.total(items);
+  }
+}
+```
+
+Use this when the caller should not know which algorithm is active.
+
+### Adapter for Third-Party Boundaries
+
+```typescript
+interface MessageBus {
+  publish(topic: string, payload: unknown): Promise<void>;
+}
+
+class RabbitBusAdapter implements MessageBus {
+  constructor(private readonly rabbit: RabbitClient) {}
+
+  publish(topic: string, payload: unknown) {
+    return this.rabbit.sendToQueue(topic, JSON.stringify(payload));
+  }
+}
+```
+
+Use this when external clients have noisy or unstable APIs.
+
+### Template Method for Lifecycle Hooks
+
+```typescript
+abstract class ManagedClient<TConfig, TClient> {
+  async connect(config: TConfig) {
+    const client = await this.create(config);
+    await this.start(client);
+    return client;
+  }
+
+  protected abstract create(config: TConfig): Promise<TClient>;
+  protected abstract start(client: TClient): Promise<void>;
+}
+```
+
+Use this when the base class owns lifecycle order and subclasses fill the variable steps.
+
+### Simple Decorator Metadata
+
+```typescript
+const HANDLER_KEY = "app:handler";
+
+function Handler(name: string): MethodDecorator {
+  return (_, __, descriptor) => {
+    Reflect.defineMetadata(HANDLER_KEY, name, descriptor.value);
+  };
+}
+```
+
+Use this when methods declare intent and another loader executes it later.
+
+## Practical Review Checklist
+
+- Can a teammate understand the public API without reading private helpers?
+- Does the type design represent real runtime rules?
+- Are names domain-specific enough to explain intent?
+- Is the pattern solving current duplication or variability?
+- Are validation, transformation, persistence, and transport concerns separated?
+- Are tests focused on behavior that the abstraction promises to preserve?

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

@@ -17,9 +17,16 @@ Use this skill for MongoDB-backed resources that rely on JokTec's Mongoose/Typeg
 - Keep schema classes, app repositories, and app-specific queries in the consumer app.
 - Extend `MongoRepo<T, ID>` for app repositories.
 - Preserve `conId` when the app has multiple Mongo connections.
-- Use schema-first decorators when a schema class should be reused as a DTO source.
+- Use schema-first decorators when a schema class should be reused as a DTO source; wrappers should reduce repeated Typegoose, validator, transformer, and Swagger stacks.
+- Use `RefId<T>` for stored reference id fields and `PopulatedRef<T>` for populated virtual fields.
+- Use `@Schema({ kind: 'embedded' })` for value objects without `_id` or timestamps.
+- Use `@Schema({ kind: 'subdocument' })` for embedded documents that need their own `_id` and timestamps.
+- Use `@Prop({ kind: 'virtual', mode: 'getter' })` for computed getters that need expose/Swagger metadata without persistence.
+- Use `@Prop({ ref: () => Target, foreignField, localField })` for populate-one virtuals when inferred defaults are enough.
+- Use `@Prop({ type: () => [Target], ref: () => Target, foreignField, localField })` for populate-array virtuals.
+- Use `@Prop({ kind: 'map', type: Object })` for map/snapshot payloads that must keep their raw shape.
 - Treat ObjectId casting and regex behavior as safety-sensitive.
-- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
+- For real migrations, inspect `node_modules/@joktec/mongo` first, then installed README or GitHub package docs, then GitHub source before assuming APIs.
 
 ## References
 

package/skills/joktec-mongo-skill/references/repository.md

@@ -4,16 +4,18 @@
 
 When blocked, inspect:
 
-- `packages/databases/mongo/README.md`
-- `packages/databases/mongo/AGENTS.md`
-- `packages/databases/mongo/src/index.ts`
-- `packages/databases/mongo/src/mongo.module.ts`
-- `packages/databases/mongo/src/mongo.service.ts`
-- `packages/databases/mongo/src/mongo.repo.ts`
-- `packages/databases/mongo/src/helpers/mongo.helper.ts`
-- `packages/databases/mongo/src/helpers/mongo.pipeline.ts`
-- `packages/databases/mongo/src/helpers/mongo.utils.ts`
-- `packages/databases/mongo/src/models/*`
+- Consumer project first: `node_modules/@joktec/mongo`.
+- Installed docs next: `node_modules/@joktec/mongo/README.md`.
+- GitHub docs next: `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mongo`.
+- GitHub source fallback:
+  - `packages/databases/mongo/src/index.ts`
+  - `packages/databases/mongo/src/mongo.module.ts`
+  - `packages/databases/mongo/src/mongo.service.ts`
+  - `packages/databases/mongo/src/mongo.repo.ts`
+  - `packages/databases/mongo/src/helpers/mongo.helper.ts`
+  - `packages/databases/mongo/src/helpers/mongo.pipeline.ts`
+  - `packages/databases/mongo/src/helpers/mongo.utils.ts`
+  - `packages/databases/mongo/src/models/*`
 
 ## Module Setup
 
@@ -35,7 +37,8 @@ Repository checklist:
 - Keep schema-specific query helpers in the app repository, not in controllers.
 - Use repository methods for standard reads so query parsing, soft delete, populate, and pagination stay consistent.
 - Pass transaction/session options through read-modify-write flows when the app uses transactions.
-- Normalize returned documents through repository/service response paths so ObjectId values do not leak unexpectedly into DTOs.
+- Repository read paths should return schema class instances with normalized ObjectId/string values, including populated and deep-populated values.
+- Code that needs raw Mongoose documents should use `MongoService.getModel(...)` or Typegoose/Mongoose APIs directly.
 
 ## Query Safety
 

package/skills/joktec-mongo-skill/references/schema-and-plugins.md

@@ -4,13 +4,20 @@
 
 When blocked, inspect:
 
-- `packages/databases/mongo/src/decorators/scheme.decorator.ts`
-- `packages/databases/mongo/src/decorators/prop.decorator.ts`
-- `packages/databases/mongo/src/decorators/props/*`
-- `packages/databases/mongo/src/models/mongo.schema.ts`
-- `packages/databases/mongo/src/plugins/paranoid.plugin.ts`
-- `packages/databases/mongo/src/plugins/strict-reference.plugin.ts`
-- `packages/databases/mongo/src/plugins/transform.plugin.ts`
+- Consumer project first: `node_modules/@joktec/mongo`.
+- Package docs next: `node_modules/@joktec/mongo/README.md`.
+- GitHub docs next: `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mongo`.
+- GitHub source fallback:
+  - `packages/databases/mongo/src/decorators/schema.decorator.ts`
+  - `packages/databases/mongo/src/decorators/schema.options.ts`
+  - `packages/databases/mongo/src/decorators/prop.decorator.ts`
+  - `packages/databases/mongo/src/decorators/props/*`
+  - `packages/databases/mongo/src/models/mongo.ref.ts`
+  - `packages/databases/mongo/src/models/object-id.ts`
+  - `packages/databases/mongo/src/models/mongo.schema.ts`
+  - `packages/databases/mongo/src/plugins/paranoid.plugin.ts`
+  - `packages/databases/mongo/src/plugins/strict-reference.plugin.ts`
+  - `packages/databases/mongo/src/plugins/transform.plugin.ts`
 
 ## Schema Decorators
 
@@ -25,6 +32,35 @@ Best practice:
 - Pass custom validators/transforms explicitly rather than adding hidden global behavior.
 - Keep maps, snapshots, and dynamic objects explicit so helper conversion does not alter their shape.
 - Keep app-level reference semantics visible; strict reference plugin checks existence, but the app still owns domain rules.
+- Use `RefId<T>` for persisted id fields and `PopulatedRef<T>` for populated virtual instance fields.
+- Use lazy `type` resolvers such as `type: () => User` or `type: () => [User]` when the wrapper cannot infer the runtime class.
+- Use `@Schema({ kind: 'embedded' })` for value objects without `_id` or timestamps.
+- Use `@Schema({ kind: 'subdocument' })` for embedded documents that need `_id` and timestamps but should not create a collection.
+- Use `@Prop({ kind: 'virtual', mode: 'getter', comment, optional, hidden, expose, swagger })` for computed getters that only need class-transformer and Swagger metadata.
+- Use `@Prop({ ref: () => User, foreignField, localField })` for populate-one virtuals when inferred defaults are enough.
+- Use `@Prop({ type: () => [User], ref: () => User, foreignField, localField })` for populate-array virtuals.
+- Use `@Prop({ kind: 'map', type: Object })` for raw maps/snapshots instead of passing `PropType.MAP` at the call site.
+
+Common mappings:
+
+| Use case | Preferred shape |
+| --- | --- |
+| Stored single reference id | `fieldId?: RefId<User>` with `@Prop({ type: ObjectId, ref: () => User })` |
+| Stored reference id array | `fieldIds?: RefId<User>[]` with `@Prop({ type: [ObjectId], ref: () => User })` |
+| Embedded value object | `@Schema({ kind: 'embedded' })` on the nested class |
+| Embedded document | `@Schema({ kind: 'subdocument' })` on the nested class |
+| Raw map/snapshot | `@Prop({ kind: 'map', type: Object })` |
+| Populated single virtual | `field?: PopulatedRef<User>` with `@Prop({ ref: () => User, foreignField: '_id', localField: 'fieldId' })` |
+| Populated virtual array | `fields?: PopulatedRef<User>[]` with `@Prop({ type: () => [User], ref: () => User, foreignField: '_id', localField: 'fieldIds' })` |
+| Computed getter | `@Prop({ kind: 'virtual', mode: 'getter', comment: '...' }) get value() { ... }` |
+
+Populate inference:
+
+- `ref` + `localField` + `foreignField` marks the field as virtual populate.
+- Populate-one can fallback to the same class from `ref`.
+- Populate arrays still need `type: () => [Target]` because runtime reflection only sees `Array`.
+- `justOne` defaults to `true` for non-array populate fields.
+- Swagger examples default to `{}` or `[]` for populated fields unless explicitly overridden.
 
 ## Plugins
 

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

@@ -19,8 +19,11 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Treat `mysql`, `mariadb`, and `postgres` as the first-class dialects.
 - Keep `sync` explicit and normally enabled only by an owner process or development bootstrap.
 - Do not add new behavior to deprecated `MysqlFinder`; use `MysqlRepo.qb()` and `MysqlHelper` paths.
-- When migrating an entity to the new schema-first decorators, migrate the whole property decorator stack, not only the TypeORM primary key decorator.
-- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
+- 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 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.
 
 ## References
 

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

@@ -2,13 +2,29 @@
 
 ## Source Lookup
 
-When blocked, inspect:
+When blocked in a consumer project, inspect the installed package first:
+
+- `node_modules/@joktec/mysql/README.md`
+- `node_modules/@joktec/mysql/AGENTS.md` when published with the package
+- `node_modules/@joktec/mysql/dist/index.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/columns/column.type.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/timestamp.decorator.d.ts`
+
+If the installed package is missing enough detail, use the GitHub package docs next:
+
+- `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mysql`
+
+Use GitHub source only after package docs and installed types are not enough:
 
 - `packages/databases/mysql/src/decorators/table.decorator.ts`
 - `packages/databases/mysql/src/decorators/column.decorator.ts`
 - `packages/databases/mysql/src/decorators/columns/column.type.ts`
 - `packages/databases/mysql/src/decorators/columns/column.factory.ts`
 - `packages/databases/mysql/src/decorators/columns/primary.column.ts`
+- `packages/databases/mysql/src/decorators/columns/timestamp.column.ts`
+- `packages/databases/mysql/src/decorators/columns/virtual.column.ts`
+- `packages/databases/mysql/src/decorators/columns/object.column.ts`
 - `packages/databases/mysql/src/decorators/columns/string.column.ts`
 - `packages/databases/mysql/src/decorators/columns/number.column.ts`
 - `packages/databases/mysql/src/decorators/columns/transform.column.ts`
@@ -16,7 +32,7 @@ When blocked, inspect:
 
 ## Schema-First Entity Pattern
 
-Use `@Tables`, `@Column`, and `@PrimaryColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
+Use `@Tables`, `@Column`, `@PrimaryColumn`, and `@TimestampColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
 
 The new decorators are not thin TypeORM aliases. They are schema-first wrappers that compose:
 
@@ -25,11 +41,18 @@ The new decorators are not thin TypeORM aliases. They are schema-first wrappers
 - `class-transformer` expose/exclude behavior.
 - Swagger property metadata.
 
-When migrating old entities, remove duplicate property decorators from `typeorm`, `class-validator`, `class-transformer`, and Swagger when the wrapper option can represent the same behavior.
+The wrapper can also represent virtual computed getters and nested JSON/jsonb class payloads. Do not use this package for Mongo/ObjectId columns.
+
+Wrapper philosophy:
 
-## Legacy Decorator Migration
+- prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
+- use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- 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
 
-Migrate a whole property at a time. Do not only replace `PrimaryGeneratedColumn`.
+## Current Decorator Capabilities
+
+Use the package README and actual installed source for full migration details. This skill only keeps the common mappings that help an agent recognize old patterns.
 
 Common mappings:
 
@@ -38,11 +61,21 @@ Common mappings:
 | `@PrimaryGeneratedColumn()` | `@PrimaryColumn('increment')` |
 | `@PrimaryGeneratedColumn('uuid')` | `@PrimaryColumn('uuid')` |
 | app-generated ordered UUID id | `@PrimaryColumn('uuidv7')` |
+| `@CreateDateColumn(...)` | `@TimestampColumn('create', ...)` |
+| `@UpdateDateColumn(...)` | `@TimestampColumn('update', ...)` |
+| `@DeleteDateColumn(...)` | `@TimestampColumn('delete', ...)` |
+| TypeORM `@VersionColumn(...)` | `@Column({ kind: 'version', ... })` |
+| TypeORM `@VirtualColumn(...)` | `@Column({ kind: 'virtual', mode: 'sql', query, ... })` |
+| TypeORM `@ViewColumn(...)` | `@Column({ kind: 'view', ... })` |
 | `@Column(...)` | `@Column(...)` from `@joktec/mysql` |
+| `@RelationId(...)` | `@Column({ kind: 'relation-id', relationId })` |
 | `@IsNotEmpty()` | `@Column({ required: true })` |
 | `@IsOptional()` | `@Column({ required: false })` or nullable TypeORM option when storage allows null |
 | `@IsEmail()` | `@Column({ isEmail: true })` |
 | `@IsMobilePhone()` | `@Column({ isPhone: true })` |
+| `@IsInt()` | `@Column({ isInt: true })` or an integer column type |
+| `@IsUUID()` | `@Column({ isUUID: true })` |
+| `@IsObject()` | `@Column({ isObject: true })` or a JSON column |
 | `@IsHexColor()` | `@Column({ isHexColor: true })` |
 | `@IsUrl()` | `@Column({ isUrl: true })` |
 | `@MinLength(n)` | `@Column({ minLength: n })` |
@@ -53,53 +86,28 @@ Common mappings:
 | `@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` |
+| `@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 |
+
+## 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:
+
+- `immutable` has priority over `update: false`
+- `update: false` implies Swagger `readOnly` only when `immutable` is not set
+- `swagger.readOnly` remains the final explicit override
+
+Some field kinds default to API read-only because they are system-managed or computed:
 
-Preserve decorators only when the wrapper cannot express them, by passing them through `decorators: [...]`.
-
-Migration checklist:
-
-- Replace TypeORM column decorators with wrappers from `@joktec/mysql`.
-- Remove duplicate `class-validator` decorators when equivalent wrapper options exist.
-- Remove duplicate `class-transformer` decorators when `hidden` or `groups` expresses the same behavior.
-- Move Swagger examples/descriptions/limits into wrapper options where possible.
-- Preserve custom validators/transforms only through `decorators: [...]`.
-- Keep database-specific options such as `type`, `length`, `nullable`, `unique`, `default`, `enum`, and `comment`.
-- Rebuild and run entity-related tests after migration because DTO metadata and TypeORM metadata both change.
-
-Example migration:
-
-```ts
-// Before
-@Column({ type: 'varchar', length: 255 })
-@IsEmail()
-@IsNotEmpty()
-@Expose()
-@ApiProperty({ example: 'user@example.com' })
-email!: string;
-
-// After
-@Column('varchar', {
-  length: 255,
-  required: true,
-  isEmail: true,
-  example: 'user@example.com',
-})
-email!: string;
-```
-
-For hidden fields:
-
-```ts
-// Before
-@Column({ type: 'varchar', length: 255 })
-@Exclude({ toPlainOnly: true })
-@ApiHideProperty()
-password!: string;
-
-// After
-@Column('varchar', { length: 255, hidden: true })
-password!: string;
-```
+- primary keys
+- timestamp columns
+- version columns
+- view columns
+- virtual getter and SQL virtual columns
+- relation-id columns
+- tree level columns
 
 ## Primary Keys
 

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

@@ -2,7 +2,21 @@
 
 ## Source Lookup
 
-When blocked, inspect:
+When blocked in a consumer project, inspect installed package docs and types first:
+
+- `node_modules/@joktec/mysql/README.md`
+- `node_modules/@joktec/mysql/AGENTS.md` when published with the package
+- `node_modules/@joktec/mysql/dist/index.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.module.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.service.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.repo.d.ts`
+- `node_modules/@joktec/mysql/dist/models/mysql.request.d.ts`
+
+If the installed package is insufficient, read GitHub package docs next:
+
+- `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mysql`
+
+Use GitHub source only after installed types and package docs are not enough:
 
 - `packages/databases/mysql/README.md`
 - `packages/databases/mysql/AGENTS.md`

package/skills/joktec-tool-skill/references/tools.md

@@ -19,6 +19,7 @@ Best practice:
 - Use the package service for outbound HTTP so retry/proxy/metrics behavior stays centralized.
 - Keep external endpoint URLs and credentials in runtime config.
 - Be careful with ESM/CommonJS import changes in HTTP/Axios ecosystem packages.
+- `HttpService.buildAgent(proxy, opts)` expects proxy identity in `HttpProxyConfig` and agent tuning in Node `AgentOptions`; inspect the installed source before adapting to proxy-agent major-version changes.
 - Test request behavior with mocks unless the test is an explicit consumer integration scenario.
 
 ## File