@joktec/skills 0.1.2 → 0.1.4

package/dist/codex/skills/joktec-database-extended-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-database-extended-skill
 description: Use when working with extended JokTec database packages @joktec/elastic, @joktec/arango, or @joktec/bigquery in a consumer app, including app-neutral client setup, config-driven lifecycle, and package-specific query/service usage.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Extended Database Skill
@@ -19,6 +23,7 @@ Use this skill for database clients that are not Mongo or MySQL.
 - Use package services for client lifecycle and connection config.
 - Do not claim parity with Mongo/MySQL repository behavior unless the package implements it.
 - Use package README and source as final truth before adding advanced behavior.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/dist/codex/skills/joktec-database-extended-skill/references/extended-databases.md

@@ -1,5 +1,15 @@
 # Extended Database Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/databases/README.md`
+- `packages/databases/AGENTS.md`
+- `packages/databases/<package>/README.md`
+- `packages/databases/<package>/src/index.ts`
+- package config/module/service files under `src/`
+
 ## Package Boundaries
 
 Extended database packages expose reusable clients and helpers for specific data systems. They should not contain consumer app schemas or business-specific query policy.
@@ -9,3 +19,17 @@ Extended database packages expose reusable clients and helpers for specific data
 - Elastic may depend on `@joktec/http` for HTTP-backed behavior.
 - Arango and BigQuery are separate client packages; verify the README/source before assuming repository-like CRUD support.
 - Use local package tests or consumer harnesses only when the target service stack is available.
+
+## Best Practices
+
+- Treat these packages as client wrappers unless source explicitly exposes a repository abstraction.
+- Keep index names, dataset names, query templates, and domain-specific projections in the consumer app.
+- Validate credentials and endpoints through config; never commit service account data.
+- Keep retries, timeouts, and debug logging visible in config.
+- Use provider-specific tests/mocks for package logic and live stack tests only when credentials/services are intentionally available.
+
+## Anti-Patterns
+
+- Do not apply MongoRepo/MysqlRepo assumptions to Elastic/Arango/BigQuery.
+- Do not introduce app schemas or business query policy into reusable database clients.
+- Do not claim support for a provider feature unless the package source or README shows it.

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

@@ -25,6 +25,7 @@ Start here when a task mentions JokTec generally, multiple `@joktec/*` packages,
 - Prefer config-driven module setup and `conId` when a package supports multiple clients.
 - Preserve NestJS module boundaries, dependency injection, lifecycle hooks, and exported package APIs.
 - Do not invent behavior for unfinished or missing packages.
+- If a focused skill is loaded without this entrypoint, still apply source-first lookup before assuming APIs.
 
 ## Reference
 

package/dist/codex/skills/joktec-framework-skill/references/framework-map.md

@@ -1,5 +1,24 @@
 # JokTec Framework Map
 
+## Source-First Operating Protocol
+
+Treat this skill pack as curated guidance, not the final implementation truth. When a task is unclear, or when a package API seems different from the skill text:
+
+1. Inspect the consumer project first to understand the package versions and local usage pattern.
+2. Prefer local framework source at `../joktec-framework` when available.
+3. Read package `README.md`, nearest `AGENTS.md`, and `src/index.ts` before changing code.
+4. If local source is unavailable, use `https://github.com/joktec/joktec-framework` as fallback.
+5. Do not invent behavior that is not visible in framework source or package docs.
+6. If package docs and source conflict, source code wins and the mismatch should be treated as documentation drift.
+
+High-value source files:
+
+- `AGENTS.md` and `docs/agents/*` for framework-level architecture and runtime policy.
+- `packages/<family>/AGENTS.md` for family boundaries.
+- `packages/<family>/<package>/README.md` for developer-facing usage.
+- `packages/<family>/<package>/src/index.ts` for public API.
+- Package config/module/service/repository files for real runtime behavior.
+
 ## Package Families
 
 - `@joktec/core`: bootstrap, config, logger, metrics, guards, base abstractions, transports, pagination, Bull.
@@ -17,9 +36,24 @@
 
 Consumer apps depend on concrete `@joktec/*` packages. Concrete packages usually depend on `@joktec/core` and `@joktec/utils`. Keep app-specific schemas, handlers, and business semantics outside reusable packages.
 
+Do not reverse the dependency direction:
+
+- reusable packages must not import from `apps/`
+- `common` packages must not depend on concrete adapters/brokers/databases
+- consumer apps own business workflows, DTO composition, schemas/entities, queue names, topics, and provider credentials
+
 ## Common Consumer App Pattern
 
 1. Register package modules in the app module or repository module.
 2. Keep app schemas/entities and app repositories in the consumer app.
 3. Extend the package repository base class when the package provides one.
 4. Use `BaseService`, `BaseController`, or transport helpers from `@joktec/core` when the app follows standard CRUD or message patterns.
+
+## Skill Selection
+
+- Use `joktec-common-skill` for BaseController/BaseService/config/pagination/client lifecycle/utils/cron.
+- Use `joktec-mongo-skill` when the resource uses Mongo schemas, MongoRepo, Typegoose decorators, plugins, or ObjectId-safe queries.
+- Use `joktec-mysql-skill` when the resource uses TypeORM entities, MysqlRepo, SQL dialect behavior, transactions, or schema-first column decorators.
+- Use broker/adapter/integration/tool skills for provider wiring; keep business semantics in the consumer app.
+
+When using the ecosystem `npx skills` installer, install `joktec-framework-skill` and `joktec-common-skill` together with any focused package skill. The current ecosystem installer does not auto-resolve dependencies from frontmatter.

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

@@ -1,6 +1,10 @@
 ---
 name: joktec-integration-skill
 description: Use when wiring or using JokTec integration packages @joktec/firebase or @joktec/gpt, including validated config, SDK client lifecycle, app-neutral integration services, credentials handling, and consumer app composition.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Integration Skill
@@ -18,6 +22,7 @@ Use this skill for third-party integration packages.
 - Use package services instead of direct SDK initialization in app code.
 - Preserve app-neutral service behavior; consumer apps own domain workflows.
 - Verify current package README/source before relying on advanced provider features.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/dist/codex/skills/joktec-integration-skill/references/integrations.md

@@ -1,9 +1,38 @@
 # Integration Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/integrations/README.md`
+- `packages/integrations/AGENTS.md`
+- `packages/integrations/<package>/README.md`
+- `packages/integrations/<package>/src/index.ts`
+- package config/module/service files under `src/`
+
 ## Firebase
 
 Use the integration module and service to initialize Firebase Admin clients from validated config. Keep credential files local or environment-provided.
 
+Best practice:
+
+- Keep service account JSON, private keys, and project credentials out of git.
+- Prefer environment-specific config or ignored local credential files.
+- Keep notification/user/storage/product semantics in the consumer app.
+- Mock Firebase Admin SDK in package tests; use live credentials only in explicit integration environments.
+
 ## GPT
 
 Use the integration package for reusable GPT client setup. Keep prompt/business policy in the consumer app, not in the generic package.
+
+Best practice:
+
+- Keep prompts, model choice policy, tool schemas, and product safety rules in the consumer app.
+- Keep API keys in secret management or environment config.
+- Verify current package completeness before relying on advanced APIs; `@joktec/gpt` may lag behind provider SDK changes.
+
+## Anti-Patterns
+
+- Do not commit real credential files.
+- Do not encode product-specific prompts or notification logic into the reusable integration package.
+- Do not assume provider SDK behavior without checking package source and provider docs when APIs are unstable.

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

@@ -1,6 +1,10 @@
 ---
 name: joktec-mongo-skill
 description: Use when working with @joktec/mongo in a consumer app, including MongoModule setup, Typegoose schema decorators, MongoRepo, MongoService, MongoHelper, plugins, ObjectId/query safety, soft delete, strict references, and cursor pagination.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Mongo Skill
@@ -15,6 +19,7 @@ Use this skill for MongoDB-backed resources that rely on JokTec's Mongoose/Typeg
 - Preserve `conId` when the app has multiple Mongo connections.
 - Use schema-first decorators when a schema class should be reused as a DTO source.
 - 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.
 
 ## References
 

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

@@ -1,13 +1,42 @@
 # Mongo Repository Usage
 
+## Source Lookup
+
+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/*`
+
 ## Module Setup
 
 Register schemas with `MongoModule.forRoot({ conId, models: [...] })`. Use the same `conId` in app repositories when using non-default connections.
 
+Best practice:
+
+- Register app schema classes in the consumer app repository module.
+- Use one owner process for index creation in multi-process deployments.
+- Preserve `conId` through service/repo constructors for multi-connection apps.
+- Do not rely on the global mongoose model registry when `MongoService` provides connection-aware resolution.
+
 ## Repository Pattern
 
 Extend `MongoRepo` and pass the schema class to the base constructor. Services can then use `BaseService` from `@joktec/core`.
 
+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.
+
 ## Query Safety
 
 - Root `id` can act as an API alias for `_id` in query conditions.
@@ -15,6 +44,20 @@ Extend `MongoRepo` and pass the schema class to the base constructor. Services c
 - `$like`, `$begin`, and `$end` escape regex input by default.
 - Do not rely on broad conversion when storing raw snapshots, maps, or nested subdocuments.
 
+Anti-patterns:
+
+- Do not convert every nested `id` key into `_id`; only API-facing query aliases should be converted.
+- Do not cast every 24-character hex string into ObjectId; fields like `externalId`, `code`, and `slug` may be strings.
+- Do not inject soft-delete conditions into unknown nested aggregate branches unless the target collection is known.
+
 ## Pagination
 
 `MongoRepo.paginate` supports page, offset, and cursor responses. Cursor mode defaults to `_id`; custom `cursorKey` appends `_id` as a tie-breaker.
+
+Cursor checklist:
+
+- Use `_id` for default Mongo cursor ordering.
+- Use `createdAt` or another indexed stable key when the product requires chronological cursor behavior.
+- Append `_id` as a tie-breaker for non-unique cursor keys.
+- Fetch `limit + 1` records and generate `nextCursor` only when another page exists.
+- Treat cursor tokens as opaque; clients should not parse them.

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

@@ -1,17 +1,46 @@
 # Mongo Schema And Plugins
 
+## Source Lookup
+
+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`
+
 ## Schema Decorators
 
 Use `@Schema` and `@Prop` wrappers from `@joktec/mongo` for Typegoose schema metadata plus validation, transform, and Swagger metadata.
 
 Avoid mutating shared option objects across multiple properties.
 
+Best practice:
+
+- Use schema-first decorators when the schema should be reused by DTO mapped types.
+- Keep raw `@prop` or raw Mongoose decorators only when the wrapper cannot express the behavior.
+- 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.
+
 ## Plugins
 
 - Paranoid plugin handles soft delete filtering and must respect aggregate first-stage constraints such as `$geoNear`.
 - Strict reference plugin validates referenced documents and must resolve models through the active connection.
 - Transform plugin centralizes common document transformation and should not break Mongo update operators.
 
+Plugin checklist:
+
+- Paranoid aggregate injection must not come before `$geoNear`.
+- Strict reference checks must be connection-aware in multi-connection apps.
+- Transform behavior must preserve update operators such as `$set`, `$inc`, `$push`, and `$addToSet`.
+- Do not treat plugins as a replacement for app authorization or domain validation.
+
 ## Debug Output
 
 Use `mongoDebug(collection, method, ...args)` when a Mongoose debug callback should be rendered as a Mongo shell-friendly command.
+
+Debug output is for developer diagnostics. Do not log credentials or sensitive document payloads in production logs.

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

@@ -1,6 +1,10 @@
 ---
 name: joktec-mysql-skill
 description: Use when working with @joktec/mysql in a consumer app, including MysqlModule setup, TypeORM entities, schema-first @Column/@PrimaryColumn decorators, MysqlRepo, MysqlService, transactions, dialect support, uuidv7 ids, query safety, and cursor pagination.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec MySQL Skill
@@ -15,8 +19,10 @@ 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.
 
 ## References
 
 - Read `references/repository.md` for connection lifecycle, repository usage, query safety, transaction, and cursor behavior.
-- Read `references/entities.md` for `@Tables`, `@Column`, `@PrimaryColumn`, uuidv7, and dialect guidance.
+- Read `references/entities.md` for `@Tables`, `@Column`, `@PrimaryColumn`, uuidv7, dialect guidance, and legacy decorator migration rules.

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

@@ -1,14 +1,114 @@
 # MySQL Entity Decorators
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `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/string.column.ts`
+- `packages/databases/mysql/src/decorators/columns/number.column.ts`
+- `packages/databases/mysql/src/decorators/columns/transform.column.ts`
+- `packages/databases/mysql/src/decorators/columns/swagger.column.ts`
+
 ## 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.
 
+The new decorators are not thin TypeORM aliases. They are schema-first wrappers that compose:
+
+- TypeORM column/primary column metadata.
+- `class-validator` behavior through `@joktec/utils` validators.
+- `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.
+
+## Legacy Decorator Migration
+
+Migrate a whole property at a time. Do not only replace `PrimaryGeneratedColumn`.
+
+Common mappings:
+
+| Legacy decorators | New decorator shape |
+| --- | --- |
+| `@PrimaryGeneratedColumn()` | `@PrimaryColumn('increment')` |
+| `@PrimaryGeneratedColumn('uuid')` | `@PrimaryColumn('uuid')` |
+| app-generated ordered UUID id | `@PrimaryColumn('uuidv7')` |
+| `@Column(...)` | `@Column(...)` from `@joktec/mysql` |
+| `@IsNotEmpty()` | `@Column({ required: true })` |
+| `@IsOptional()` | `@Column({ required: false })` or nullable TypeORM option when storage allows null |
+| `@IsEmail()` | `@Column({ isEmail: true })` |
+| `@IsMobilePhone()` | `@Column({ isPhone: true })` |
+| `@IsHexColor()` | `@Column({ isHexColor: true })` |
+| `@IsUrl()` | `@Column({ isUrl: true })` |
+| `@MinLength(n)` | `@Column({ minLength: n })` |
+| `@MaxLength(n)` | `@Column({ maxLength: n })` |
+| `@Min(n)` | `@Column({ min: n })` |
+| `@Max(n)` | `@Column({ max: n })` |
+| `@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` |
+
+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
 
 - Prefer numeric auto-increment keys for write-heavy MySQL tables.
 - Use UUIDs when the app needs globally unique or public identifiers.
 - Prefer `uuidv7` over random UUIDs when the id participates in ordered indexes or cursor-like access.
+- When switching from UUID v4 to uuidv7, verify downstream code does not assume random UUID ordering.
+
+Do not blindly convert every primary key to uuidv7. Keep numeric increment keys when the table is internal, write-heavy, and does not need public/global identifiers.
 
 ## Dialects
 

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

@@ -1,23 +1,72 @@
 # MySQL Repository Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/databases/mysql/README.md`
+- `packages/databases/mysql/AGENTS.md`
+- `packages/databases/mysql/src/index.ts`
+- `packages/databases/mysql/src/mysql.module.ts`
+- `packages/databases/mysql/src/mysql.service.ts`
+- `packages/databases/mysql/src/mysql.repo.ts`
+- `packages/databases/mysql/src/helpers/mysql.helper.ts`
+- `packages/databases/mysql/src/helpers/mysql.finder.ts`
+- `packages/databases/mysql/src/services/mysql.dialect.ts`
+- `packages/databases/mysql/src/models/*`
+
 ## Module Setup
 
 Register entities with `MysqlModule.forRoot({ conId, models: [...] })`. Use `conId` for multiple DataSources.
 
+Best practice:
+
+- Register consumer app entities in an app repository module.
+- Keep `sync` disabled in request-facing processes unless the app intentionally owns schema sync.
+- Use one controlled owner process for schema sync/migration in multi-process deployments.
+- Preserve `conId` when resolving repositories or transaction-scoped managers.
+
 ## Repository Pattern
 
 Extend `MysqlRepo` and pass the entity class to the base constructor. Services can use `BaseService` when CRUD behavior follows the shared contract.
 
+Repository checklist:
+
+- Keep entity-specific SQL helpers in the app repository, not in controllers.
+- Use `MysqlRepo.qb()` and repository methods for standard reads so field validation, relation loading, soft delete, and pagination stay consistent.
+- Do not add new behavior to `MysqlFinder`; it is deprecated compatibility code.
+- Keep read/write operations in the same transaction context when the app passes a manager or query runner.
+
 ## Query Safety
 
 - Validate field paths against TypeORM metadata before interpolating SQL identifiers.
 - Use parameter binding for values.
 - Keep logical operators such as `$and` and `$or` grouped through QueryBuilder behavior.
 
+Anti-patterns:
+
+- Do not interpolate user-provided field names or relation names into SQL without TypeORM metadata validation.
+- Do not assume MySQL-only syntax when the package supports MySQL, MariaDB, and Postgres.
+- Do not use a relation/populate path unless it maps to entity metadata.
+
 ## Pagination
 
 `MysqlRepo.paginate` supports page, offset, and cursor responses. Cursor mode defaults to `createdAt` plus primary key columns. Custom cursor keys must be mapped columns.
 
+Cursor checklist:
+
+- Use `createdAt + primary key` as the default stable cursor.
+- Add primary keys as tie-breakers for non-unique cursor keys.
+- Ensure cursor keys are indexed for hot list endpoints.
+- Validate cursor payload shape before building SQL.
+- Treat cursor tokens as opaque; clients should not parse them.
+
 ## Transactions
 
 When using transaction-scoped operations, pass the manager or query runner through repository options so pre-read and write operations use the same context.
+
+Transaction checklist:
+
+- Use one manager/query runner for read-modify-write flows.
+- Rollback tests should prove that both pre-read dependent writes and writes are transaction-scoped.
+- Avoid mixing default repositories and transaction-scoped repositories in one operation.

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

@@ -1,6 +1,10 @@
 ---
 name: joktec-tool-skill
 description: Use when wiring or using JokTec tool packages @joktec/http, @joktec/file, or @joktec/alert, including Axios-backed HTTP clients, file classification helpers, Slack-compatible alert webhooks, config-driven lifecycle, and app-neutral utility services.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Tool Skill
@@ -19,6 +23,7 @@ Use this skill for reusable utility services.
 - Use config-driven clients instead of direct ad hoc setup in app code.
 - Preserve retry, metrics, proxy, and upload behavior where the package exposes it.
 - Keep alert tokens and webhook URLs in runtime config only.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

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

@@ -1,13 +1,48 @@
 # Tool Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/tools/README.md`
+- `packages/tools/AGENTS.md`
+- `packages/tools/<package>/README.md`
+- `packages/tools/<package>/src/index.ts`
+- package config/module/service/helper files under `src/`
+
 ## HTTP
 
 Use `@joktec/http` for Axios-backed requests, uploads, proxy agent support, retry config, and metrics where exposed.
 
+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.
+- Test request behavior with mocks unless the test is an explicit consumer integration scenario.
+
 ## File
 
 Use `@joktec/file` for shared file helpers and classification behavior instead of duplicating local utility code.
 
+Best practice:
+
+- Keep filesystem paths and temporary directories environment-specific.
+- Validate upload/file inputs before passing them into business workflows.
+- Use package helpers for MIME/classification behavior when consistency matters across services.
+
 ## Alert
 
 Use `@joktec/alert` for Slack-compatible webhook alerts. Keep webhook URLs and credentials out of source control.
+
+Best practice:
+
+- Treat alert messages as operational notifications, not business workflows.
+- Do not leak secrets, tokens, connection strings, or personal data into alert payloads.
+- `@joktec/alert` is present but less complete than core database/client packages; inspect source before depending on advanced behavior.
+
+## Anti-Patterns
+
+- Do not scatter raw Axios instances across the app when `@joktec/http` should own shared behavior.
+- Do not commit webhook URLs or proxy credentials.
+- Do not use tool packages as hidden places for app business rules.