@wabot-dev/create 0.0.4 → 1.0.1

package/lib/skills/registry.mjs

@@ -1,64 +1,34 @@
-import { fileURLToPath } from 'url'
+import fs from 'fs'
+import path from 'path'
 
-function packagedSkill(name, description) {
-  return {
-    name,
-    description,
-    sourceDir: fileURLToPath(new URL(`../../skills/${name}`, import.meta.url)),
-  }
-}
+import { resolveFrameworkSkillsDir } from './framework-source.mjs'
 
-const skillDefinitions = {
-  'wabot-framework': packagedSkill(
-    'wabot-framework',
-    'Umbrella skill — project boot, layout, scripts, and where to dive for each subsystem',
-  ),
-  'wabot-di-config': packagedSkill(
-    'wabot-di-config',
-    'DI lifecycles, Env, and typed config references',
-  ),
-  'wabot-validation': packagedSkill(
-    'wabot-validation',
-    'Validators, @description, validateAndTransform, Mapper',
-  ),
-  'wabot-persistence': packagedSkill(
-    'wabot-persistence',
-    'Entities, repositories, query DSL, mem/pg extensions',
-  ),
-  'wabot-mindset': packagedSkill(
-    'wabot-mindset',
-    'Mindsets, modules, models, ChatOperator',
-  ),
-  'wabot-chat': packagedSkill(
-    'wabot-chat',
-    'Chat controllers, channels (cmd/socket/telegram/whatsapp/wasender), chat-bot adapters',
-  ),
-  'wabot-rest-socket': packagedSkill(
-    'wabot-rest-socket',
-    'REST and Socket.IO controllers, middlewares, handshake guards',
-  ),
-  'wabot-async': packagedSkill(
-    'wabot-async',
-    'Commands, cron handlers, @transaction, the Async service',
-  ),
-  'wabot-auth': packagedSkill(
-    'wabot-auth',
-    'Auth<D> scope, JWT and API key guards, token issuing',
-  ),
-  'wabot-ops': packagedSkill(
-    'wabot-ops',
-    'Logger, Locker, CustomError, Password, Random',
-  ),
-}
+// Skills are owned and versioned by @wabot-dev/framework. The registry discovers
+// them from the framework's packaged `skills/` directory rather than bundling its
+// own copy, so adding a skill upstream requires no change here.
 
-export function getSkill(skillName) {
-  return skillDefinitions[skillName] ?? null
+export function listSkillNames(skillsDir = resolveFrameworkSkillsDir()) {
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() && fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')),
+    )
+    .map((entry) => entry.name)
+    .sort()
 }
 
-export function listSkillNames() {
-  return Object.keys(skillDefinitions).sort()
+export function listSkills(skillsDir = resolveFrameworkSkillsDir()) {
+  return listSkillNames(skillsDir).map((name) => ({
+    name,
+    sourceDir: path.join(skillsDir, name),
+  }))
 }
 
-export function listSkills() {
-  return listSkillNames().map((name) => skillDefinitions[name])
+export function getSkill(name, skillsDir = resolveFrameworkSkillsDir()) {
+  const sourceDir = path.join(skillsDir, name)
+  if (!fs.existsSync(path.join(sourceDir, 'SKILL.md'))) {
+    return null
+  }
+  return { name, sourceDir }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wabot-dev/create",
-  "version": "0.0.4",
+  "version": "1.0.1",
   "description": "Project creator for Wabot Framework",
   "license": "ISC",
   "author": "",
@@ -11,9 +11,11 @@
   },
   "files": [
     "bin",
-    "lib",
-    "skills"
+    "lib"
   ],
+  "scripts": {
+    "test:smoke": "node scripts/smoke-skills-bulk-install.mjs && node scripts/smoke-skill-installer.mjs"
+  },
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^14.0.0",

package/skills/wabot-async/SKILL.md

@@ -1,139 +0,0 @@
----
-name: wabot-async
-description: Use when running background work in Wabot — fire-and-forget commands, scheduled deferred commands, cron handlers, or wrapping side-effectful methods in a DB transaction. Covers @command, @commandHandler, @cronHandler, @transaction, the Async service (runCommand, scheduleCommand, IScheduleAt), ICommandHandler / ICronHandler, and how the in-memory vs PG job/cron stores are wired by the project runner.
----
-
-# Async commands, cron, and transactions
-
-Wabot's async layer handles three kinds of work:
-
-- **Commands** — typed messages with a registered handler. Run immediately (`runCommand`) or scheduled (`scheduleCommand`).
-- **Crons** — handlers that fire on a cron expression.
-- **Transactions** — wrap a method so all repository writes happen inside one DB transaction per registered adapter.
-
-The job store, cron job store, and transaction adapter are auto-selected by the project runner based on `DATABASE_URL` (in-memory ↔ PostgreSQL). No manual registration.
-
-## Commands
-
-A command is a plain class decorated with `@command(name)`. Fields use the standard validators from `wabot-validation`.
-
-```typescript
-import { command, isNumber, isString, min } from '@wabot-dev/framework'
-
-@command('orders.charge')
-export class ChargeOrder {
-  @isString() orderId!: string
-  @isNumber() @min(1) amountCents!: number
-}
-```
-
-The handler implements `ICommandHandler<C>` and is bound with `@commandHandler(Command)`:
-
-```typescript
-import { commandHandler, ICommandHandler, injectable } from '@wabot-dev/framework'
-import { ChargeOrder } from './ChargeOrder'
-
-@commandHandler(ChargeOrder)
-export class ChargeOrderHandler implements ICommandHandler<ChargeOrder> {
-  constructor(private payments: PaymentService) {}
-
-  async handle(cmd: ChargeOrder) {
-    await this.payments.charge(cmd.orderId, cmd.amountCents)
-  }
-}
-```
-
-Trigger it with the `Async` singleton:
-
-```typescript
-import { Async, container } from '@wabot-dev/framework'
-
-const async = container.resolve(Async)
-
-// Run as soon as a worker is free
-await async.runCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 })
-
-// Schedule for later: absolute Date or relative delay
-await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, { minutes: 30 })
-await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, new Date('2026-12-31T08:00:00Z'))
-```
-
-`IScheduleAt = Date | { seconds: number } | { minutes: number } | { hours: number } | { days: number }`.
-
-`Async.runCommand` returns a `Job` immediately (it has an `id` you can persist). The payload is validated against the command class before the job is stored — bad shapes throw `CustomError`.
-
-`@commandHandler` applies `@injectable()`. There is at most one handler per command name; registering a second throws.
-
-## Cron handlers
-
-```typescript
-import { cronHandler, ICronHandler } from '@wabot-dev/framework'
-
-@cronHandler({ name: 'daily-cleanup', cron: '0 3 * * *' })
-export class DailyCleanup implements ICronHandler {
-  constructor(private games: GameRepository) {}
-
-  async handle() {
-    // ...
-  }
-
-  // Optional. Called when handle() throws.
-  async handleError(err: any) {
-    // ...
-  }
-}
-```
-
-- `cron` accepts standard 5-field or 6-field (with seconds) cron expressions.
-- `disabled: true` turns a handler off without removing it (useful for guarded rollouts).
-- `@cronHandler` applies `@singleton()` automatically — do not stack lifecycle decorators.
-
-The runner registers these into `CronScheduler`, which persists per-cron state in `CronJobRepository` so missed runs aren't replayed on restart.
-
-## Transactions
-
-`@transaction(dbNames?)` wraps an async method so every adapter listed runs the call inside a transaction. Without arguments, all registered adapters participate (today there is one: `'pg'` when `DATABASE_URL` is Postgres).
-
-```typescript
-import { transaction } from '@wabot-dev/framework'
-
-@injectable()
-export class Checkout {
-  @transaction(['pg'])
-  async checkout(orderId: string) {
-    await this.orderRepository.update(...)
-    await this.paymentRepository.create(...)
-  }
-}
-```
-
-Behavior:
-- Repository writes performed inside the method go to the same client/connection.
-- Throwing rolls back; returning commits.
-- Nested `@transaction`-decorated calls reuse the outer transaction (no nested begin).
-- If you decorate with `@transaction(['pg'])` and the app is running without Postgres, the call still executes but no PG transaction wraps it (the in-memory adapter is a no-op).
-
-## Manual run / stop
-
-In production the runner discovers and starts everything. For testing or custom hosts:
-
-```typescript
-import { runCommandHandlers, runCronHandlers, stopCommandHandlers, stopCronHandlers } from '@wabot-dev/framework'
-
-runCommandHandlers([ChargeOrderHandler])
-runCronHandlers([DailyCleanup])
-
-// later
-stopCommandHandlers([ChargeOrderHandler])
-stopCronHandlers([DailyCleanup])
-```
-
-`testAsync` is exported for integration tests against the real job/cron schedulers — see `wabot-ts/src/feature/async/testAsync.ts` for an example.
-
-## Rules
-
-- Command classes are *data* classes. Don't put behavior on them — that belongs in the handler.
-- Don't reuse a command name for two handlers. The framework throws on boot.
-- Don't `await async.runCommand(...)` inside a request handler expecting it to finish synchronously — `runCommand` schedules the job and returns immediately. Use `async.scheduleCommand(..., { seconds: 0 })` if you want the same fire-and-forget behavior explicitly.
-- Cron expressions in seconds (6 fields) are supported but be careful: the in-memory adapter polls fast, the PG adapter polls at a lower rate.
-- Wrap multi-repository writes in `@transaction(['pg'])` rather than chaining manual `withPgTransaction` calls.

package/skills/wabot-auth/SKILL.md

@@ -1,149 +0,0 @@
----
-name: wabot-auth
-description: Use when adding authentication to a Wabot REST endpoint or Socket.IO namespace, issuing JWT access/refresh tokens, or protecting endpoints with API keys. Covers the chat/request-scoped Auth<D> service, @jwtGuard / @jwtHandshakeGuard, JwtConfig and the JWT_* env vars, Jwt.createToken / findRefreshTokenAuthInfo, JwtRefreshToken, and @apiKeyGuard / @apiKeyHandshakeGuard with PgApiKeyRepository / RemoteApiKeyRepository.
----
-
-# Authentication
-
-Wabot's auth is request-scoped. A guard middleware verifies the credential, then writes the resolved auth info into the per-request/socket `Auth<D>` instance. Downstream code reads it with `auth.require()`.
-
-## `Auth<D>`
-
-```typescript
-import { Auth, injectable } from '@wabot-dev/framework'
-
-interface SessionInfo {
-  userId: string
-  role: 'admin' | 'user'
-}
-
-@injectable()
-export class OrdersService {
-  constructor(private auth: Auth<SessionInfo>) {}
-
-  list() {
-    const session = this.auth.require() // throws CustomError({ httpCode: 401 }) if not assigned
-    return this.repo.findByUserId(session.userId)
-  }
-}
-```
-
-`Auth` is `@scoped(Lifecycle.ContainerScoped)` and exists once per request, chat, or socket connection. Methods:
-
-- `assign(info)` — sets the auth info (used by guards). Throws if already assigned.
-- `override(info)` — replaces even when assigned (use cautiously).
-- `require()` — returns the info or throws 401.
-- `isAssigned()` / `wasOverrided()` / `clear()`.
-
-## JWT — REST
-
-```typescript
-import { jwtGuard, onGet, onPost, restController } from '@wabot-dev/framework'
-
-@restController('/account')
-export class AccountController {
-  @onGet('/me')
-  @jwtGuard()
-  async me(_, auth: Auth<SessionInfo>) {
-    return auth.require()
-  }
-}
-```
-
-`@jwtGuard()` reads `Authorization: Bearer <token>`, verifies it with `JwtConfig` (env-driven, see below), and calls `auth.assign(payload)`.
-
-## JWT — Socket
-
-```typescript
-import { jwtHandshakeGuard, socketController } from '@wabot-dev/framework'
-
-@socketController('private')
-@jwtHandshakeGuard()
-export class PrivateSocketController { /* ... */ }
-```
-
-The token is read from `socket.handshake.auth.token` first, falling back to the `Authorization` header.
-
-## Issuing tokens
-
-```typescript
-import { Auth, Jwt, JwtAccessAndRefreshTokenDto, injectable, onPost, restController } from '@wabot-dev/framework'
-
-@restController('/auth')
-export class AuthController {
-  constructor(private jwt: Jwt, private auth: Auth<SessionInfo>) {}
-
-  @onPost('/login')
-  async login(body: LoginRequest): Promise<JwtAccessAndRefreshTokenDto> {
-    const session = await this.userService.verify(body)
-    this.auth.assign(session)
-    return this.jwt.createToken({ device: body.device ?? 'unknown' })
-  }
-
-  @onPost('/refresh')
-  async refresh(body: RefreshRequest): Promise<JwtAccessAndRefreshTokenDto> {
-    const session = await this.jwt.findRefreshTokenAuthInfo(body.refreshToken)
-    this.auth.override(session)
-    return this.jwt.createToken()
-  }
-}
-```
-
-`Jwt.createToken(metadata?)`:
-- Reads the current `auth.require()` info.
-- Persists a `JwtRefreshToken` via `JwtRefreshTokenRepository` (the runner picks `PgJwtRefreshTokenRepository` under PG; you can register your own).
-- Returns `{ access: { token, expiration }, refresh: { token, expiration } }`.
-
-`Jwt.findRefreshTokenAuthInfo(secret)` validates the refresh secret (hash-compare + expiration + revocation) and returns the original auth payload. Throws 401 if any check fails.
-
-### Env vars
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `JWT_SECRET` | (required) | Symmetric secret or asymmetric key used for sign/verify |
-| `JWT_ALGORITHM` | `HS256` | Any `jsonwebtoken.Algorithm` |
-| `JWT_ACCESS_EXPIRATION_SECONDS` | `600` (10 min) | Access token lifetime |
-| `JWT_REFRESH_EXPIRATION_SECONDS` | `31536000` (1 yr) | Refresh token lifetime |
-
-`JwtConfig` is `@singleton()` and reads these at boot.
-
-### Refresh-token metadata
-
-`JwtRefreshToken<D>` exposes `metadata` (the arbitrary `Record<string, string>` you passed to `createToken`), `expirationTime`, `revoke()`, and `isValidToken(secret)`. The repository exposes `findByMetadata(metadata)` so you can revoke all tokens issued to a device.
-
-## API key
-
-```typescript
-import { apiKeyGuard, apiKeyHandshakeGuard, onGet, restController, socketController } from '@wabot-dev/framework'
-
-@restController('/internal')
-export class InternalController {
-  @onGet('/health')
-  @apiKeyGuard()
-  async health() { return { ok: true } }
-}
-
-@socketController('admin')
-@apiKeyHandshakeGuard()
-export class AdminSocketController { /* ... */ }
-```
-
-The guard reads the `X-Api-Key` header (REST) or `socket.handshake.auth.apiKey` (socket), validates via `ApiKeyRepository`, and assigns the lookup result to `Auth`.
-
-`ApiKeyRepository` defaults to `PgApiKeyRepository` under Postgres. A `RemoteApiKeyRepository` is also exported for delegating validation to an external service:
-
-```typescript
-import { container, ApiKeyRepository, RemoteApiKeyRepository } from '@wabot-dev/framework'
-
-container.registerType(ApiKeyRepository, RemoteApiKeyRepository)
-```
-
-Set `WABOT_API_KEY` and `WABOT_LLM_URL` to point `RemoteApiKeyRepository` at your auth service (it expects the same shape as the Wabot platform).
-
-## Rules
-
-- Always type `Auth<D>` with your session shape. `auth.require()` returns the typed value.
-- A guard runs once per request/connection. Don't reassign manually — use `override(...)` only on token refresh.
-- `@jwtGuard()` and `@apiKeyGuard()` work on REST endpoints; their `*HandshakeGuard()` variants work on socket controllers. Don't mix them up.
-- Never log `auth.require()` results — they may contain PII or token claims. Use a redacted view.
-- If you need a custom guard, implement `IMiddleware` (REST) or `IHandshakeMiddleware` (socket) and wire it with `@middleware(...)` / `@handshakeMiddlewares([...])`.

package/skills/wabot-chat/SKILL.md

@@ -1,136 +0,0 @@
----
-name: wabot-chat
-description: Use when wiring chat input/output for a Wabot bot — receiving messages from one or more channels (cmd, socket, telegram, whatsapp, wasender), injecting a ChatBot bound to a mindset, and replying. Covers @chatController, @chatBot, @cmd / @socket / @telegram / @whatsApp / @wasender, IReceivedMessage, the ChatBot.sendMessage callback, and the @chatAdapter / runChatAdapters provider model.
----
-
-# Chat controllers, channels, and adapters
-
-A chat controller is the entry point for messages from a transport (terminal, socket, Telegram, WhatsApp). It owns a `ChatBot` bound to one mindset and forwards the message into the bot's processing loop.
-
-## Controller shape
-
-```typescript
-import {
-  chatBot,
-  ChatBot,
-  chatController,
-  cmd,
-  socket,
-  telegram,
-  whatsApp,
-  type IReceivedMessage,
-} from '@wabot-dev/framework'
-import { PixelMindset } from './mindset/PixelMindset'
-
-@chatController()
-export class PixelChatController {
-  constructor(@chatBot(PixelMindset) private pixel: ChatBot) {}
-
-  @cmd()
-  @socket({ namespace: 'pixel' })
-  @telegram({ botToken: process.env.TELEGRAM_BOT_TOKEN! })
-  @whatsApp({ number: '+1555…', accessToken: '…', businessNumberId: '…' })
-  async onMessage(ctx: IReceivedMessage) {
-    await this.pixel.sendMessage(ctx.message, async (reply) => {
-      await ctx.reply(reply)
-    })
-  }
-}
-```
-
-Channel decorators stack: each one registers the same method on a different transport. The runner instantiates a channel per registration.
-
-`@chatController()` takes no arguments today — `IchatControllerConfig` is currently empty. It applies `@injectable()`.
-
-## `ChatBot` injection
-
-`@chatBot(MindsetCtor)` injects a `ChatBot` instance scoped to that mindset. You can have several in one controller (e.g. a "support" bot and a "sales" bot) — each gets a unique injection token under the hood.
-
-`ChatBot.sendMessage(message, callback)`:
-- Persists the incoming message as a `humanMessage` chat item.
-- Calls the mindset → adapter loop, executing any tool calls.
-- Invokes `callback(replyMessage)` once per `botMessage` item produced.
-
-Inside the loop, the bot picks `models.visionLlm` if any image is attached, otherwise `models.llm`. It will only use providers registered through `@chatAdapter` (see below).
-
-## `IReceivedMessage` and `IChatMessage`
-
-```typescript
-interface IReceivedMessage {
-  message: IChatMessage
-  reply: (message: IChatMessage) => Promise<Record<string, string> | void>
-}
-
-interface IChatMessage {
-  senderId?: string
-  senderName?: string
-  text?: string
-  images?: IChatMessageImage[]
-  documents?: IChatMessageDocument[]
-  object?: object
-  metadata?: Record<string, string>
-}
-```
-
-The `reply` callback comes from the channel — for `@cmd` it writes to stdout of the connected `cmd:channel` client; for `@socket` it emits a Socket.IO event; for `@telegram`/`@whatsApp`/`@wasender` it calls the provider's send API. You always pass an `IChatMessage` (with `text`, `images`, or `documents`); never raw strings.
-
-## Channels — what each decorator needs
-
-| Decorator | Config | Notes |
-| --- | --- | --- |
-| `@cmd()` | none | Local Unix socket terminal client. Run `npm run cmd:channel` to chat. State stored under `.wabot/cmd-channel/<route>/`. |
-| `@socket({ namespace })` | `namespace: string \| ConfigReference<string>` | Mounts a Socket.IO namespace. Tag-fn refs (`str\`socket.namespace\``) supported. |
-| `@telegram({ botToken })` | `botToken: string` | Long-poll Telegram bot. Pass the raw token. |
-| `@whatsApp(numberOrConfig)` | string OR `{ number, accessToken?, businessNumberId? }` (each may be a `ConfigReference`) | WhatsApp Cloud API. |
-| `@wasender(config?)` | `{ apiKey?, webhookSecret?, phoneNumber?, webhookPath? }` (each may be a `ConfigReference`) | WaSender integration. |
-
-Channel configs that accept `ConfigReference` resolve env vars automatically — use `str\`wasender.apiKey\`` from `@wabot-dev/framework` to point to `WASENDER_APIKEY`.
-
-## Chat resolution
-
-When a message arrives, `ChatResolver` looks up the `Chat` by `IChatConnection` (`{ chatType: 'PRIVATE' | 'GROUP', channelName, id }`). If none exists, a new `Chat` is created under a lock. You never write this resolution code — it's already wired.
-
-Inside a chat handler, these tokens are available in the child container:
-- `Chat` — the resolved chat entity
-- `ChatMemory` — append/read chat items for this chat
-- `ChatOperator` — convenience wrapper (see `wabot-mindset`)
-- `Auth` — populated if the channel attached auth (e.g. via `injectInstances`)
-
-## Chat adapters (providers)
-
-Each LLM provider has a `@chatAdapter({ provider: 'name' })` class implementing `IChatAdapter.nextItems`. The framework ships adapters for `openai`, `anthropic`, `google`, `openrouter`, `deepseek`, and `wabot`.
-
-The project runner registers adapters automatically based on env keys (`OPENAI_API_KEY` → OpenAI, etc.). To override, pass `chatAdapters: [...]` to `run({ chatAdapters: [MyAdapter, OpenaiChatAdapter] })`.
-
-To call them manually (outside the runner):
-
-```typescript
-import { runChatAdapters, OpenaiChatAdapter } from '@wabot-dev/framework'
-runChatAdapters([OpenaiChatAdapter])
-```
-
-`runChatAdapters` binds a `UnionChatAdapter` to the `ChatAdapter` token — it dispatches by `IMindsetModelRef.provider`.
-
-To build your own adapter, implement `IChatAdapter`:
-
-```typescript
-import { chatAdapter, IChatAdapter, IChatAdapterNextItemsReq, IChatAdapterNextItemsRes, singleton } from '@wabot-dev/framework'
-
-@chatAdapter({ provider: 'my-llm' })
-@singleton()
-export class MyLlmAdapter implements IChatAdapter {
-  async nextItems(req: IChatAdapterNextItemsReq): Promise<IChatAdapterNextItemsRes> {
-    // map req.systemPrompt + req.prevItems + req.tools to your API, return { nextItems, usage }
-    return { nextItems: [], usage: { inputTokens: 0, outputTokens: 0, provider: 'my-llm', model: req.models[0].model } }
-  }
-}
-```
-
-## Rules
-
-- Keep controllers thin — fetch from `ctx.message`, call `bot.sendMessage`, return. Business logic belongs in modules/services.
-- Don't pass raw strings to `ctx.reply` — wrap them in `{ text: '...' }`.
-- The reply callback is async; await it so the channel actually flushes.
-- `@chatBot(Mindset)` is a parameter decorator — it can only appear in a constructor.
-- If you add a new chat adapter, its file must be imported during the runner's scan (so the `@chatAdapter` side-effect runs); place it inside `directories`.
-- Avoid building a mindset/controller pair when one controller can route between several mindsets with multiple `@chatBot(...)` constructor params.

package/skills/wabot-di-config/SKILL.md

@@ -1,117 +0,0 @@
----
-name: wabot-di-config
-description: Use when wiring services, choosing service lifecycles, reading env vars, or expressing typed config references for Wabot apps. Covers @injectable / @singleton / @scoped / @inject, the container, the Env service, and the config tag functions (str, num, bool, obj, strArr, numArr, boolArr) that drive resolveConfigReferences in channel and adapter decorators.
----
-
-# DI, Env, and config references
-
-Wabot uses `tsyringe` under the hood and re-exports the pieces you need from `@wabot-dev/framework`:
-
-```typescript
-import { container, injectable, singleton, scoped, Lifecycle, inject } from '@wabot-dev/framework'
-```
-
-## Lifecycles
-
-| Decorator | When to use | Example |
-| --- | --- | --- |
-| `@singleton()` | App-wide infra: clients, repositories, config holders, caches. One instance for the process. | DB clients, adapters |
-| `@injectable()` | Stateless / per-resolution services. Each `resolve` returns a new instance. | Calculators, mappers |
-| `@scoped(Lifecycle.ContainerScoped)` | Per-request / per-chat / per-socket state. Lives in the child container created by the runner. | `Auth`, request context |
-
-The framework already creates child containers for every chat message, REST request, and socket connection. `ContainerScoped` services do not leak across them.
-
-```typescript
-import { injectable, singleton, scoped, Lifecycle } from '@wabot-dev/framework'
-
-@singleton()
-export class ProductCache {
-  private byId = new Map<string, string>()
-  put(id: string, name: string) { this.byId.set(id, name) }
-}
-
-@injectable()
-export class QuoteCalculator {
-  total(base: number, discount: number) { return base - base * discount }
-}
-
-@scoped(Lifecycle.ContainerScoped)
-export class RequestContext {
-  private userId?: string
-  setUserId(id: string) { this.userId = id }
-  requireUserId() {
-    if (!this.userId) throw new Error('Unauthorized')
-    return this.userId
-  }
-}
-```
-
-Decorators that mark something as a controller/handler also apply `@injectable()` for you (`@chatController`, `@restController`, `@socketController`, `@commandHandler`, `@cronHandler`, `@mindset`, `@mindsetModule`). Do not stack lifecycle decorators on top of those — they will conflict.
-
-## Resolving and registering
-
-```typescript
-import { container, inject, injectable } from '@wabot-dev/framework'
-
-container.register('SMTP_HOST', { useValue: 'smtp.example.com' })
-container.register('SMTP_PORT', { useValue: 587 })
-
-@injectable()
-export class Mailer {
-  constructor(
-    @inject('SMTP_HOST') private host: string,
-    @inject('SMTP_PORT') private port: number,
-  ) {}
-}
-```
-
-You rarely need `container.register*` in app code — for chat/REST/socket components the runner does it. Use registration only for:
-
-- Replacing a default infra binding (e.g. swap `Locker` for a custom implementation).
-- Providing typed config values to classes you cannot decorate.
-- Bootstrapping in tests.
-
-`container.registerInstance(Token, value)` and `container.registerType(From, To)` are the two most common helpers.
-
-## `Env`
-
-```typescript
-import { container, Env } from '@wabot-dev/framework'
-
-const env = container.resolve(Env)
-
-const dbUrl = env.requireString('DATABASE_URL')
-const port = env.requireNumber('PORT', { default: 3000 })
-const isDev = env.isDevelopment() // controlled by WABOT_ENV: 'development' | 'staging' | 'testing' | 'production'
-```
-
-`Env.requireString` / `requireNumber` throw if the variable is missing and no `default` is provided.
-
-## Config tag functions
-
-Some addon decorators (e.g. `@socket`, `@whatsApp`, `@wasender`) accept a config object whose fields may be `ConfigReference` values produced by tag functions. The reference is resolved by `resolveConfigReferences` (called inside the decorator) against `process.env`, with the path translated to UPPER_SNAKE_CASE.
-
-```typescript
-import { socket } from '@wabot-dev/framework' // tag fns also exported from the package root
-import { str, num, bool, obj, strArr, numArr, boolArr } from '@wabot-dev/framework'
-
-@socket({
-  // Resolved from env: SOCKET_NAMESPACE; defaults to "chat" if env is missing.
-  namespace: str`socket.namespace:chat`,
-  maxConnections: num`socket.max:100`,
-})
-class MyController { /* ... */ }
-```
-
-Syntax: `<fn>\`path.with.dots:default\``. The default after the colon is optional. Only literal strings are allowed; interpolation throws.
-
-Available factories: `str`, `num`, `bool`, `obj` (parses JSON), `strArr`, `numArr`, `boolArr` (comma-separated).
-
-If you call `resolveConfigReferences(cfg)` yourself it returns a typed object where each `ConfigReference<T>` field is replaced by `T`.
-
-## Rules
-
-- Default to `@injectable()` for new code. Promote to `@singleton()` only when state must be shared.
-- `@scoped(Lifecycle.ContainerScoped)` only when the value must not leak across requests, chats, or socket connections.
-- Don't call `container.resolve(...)` inside a constructor — declare dependencies as constructor parameters and let DI inject them.
-- Use `Env.requireString/requireNumber` for plain env reads; use config tag functions only inside decorator configs that the framework already resolves.