chore(agents): streamline skills, add a skills validator, tighten public error contract (#1110)

Trim the `.agents/skills/` runbooks to what agents actually need at read time
and add `scripts/check-skills.mjs` so malformed skills fail `pnpm lint` instead
of shipping silently.

- Condense 14 SKILL.md runbooks (-875 lines); drop the two
  `source-command-*` skills that only mirrored slash commands
- Add `check-skills.mjs`: frontmatter, directory/name match, dangling
  symlinks, and CLAUDE.md routing-table coverage; wire into
  `check:agent-instructions`
- Remove the stale `.claude/skills/shadcn` and `.cursor/skills` symlinks
- CLAUDE.md routing table gains `chatbotx-basecode` and `builder-ui-i18n`;
  AGENTS.md now points at that table as the single inventory
- Sync invariant mirrors: correct the `ChannelType` source of truth to
  `packages/utils/src/channel.ts`, add the structured-logging (`err`, not
  `error`) invariant
- Public API: move `invalidRequestData` + `validation` into
  `commonApiErrors` so every input-taking route documents its 422, mark the
  per-router sets `satisfies ErrorMap`, and fix contact-notes create to
  declare `notFound` (its identifier lookup can 404)
- Cover both with tests that read each procedure's real `errorMap` rather
  than the rendered spec


Claude-Session: https://claude.ai/code/session_012bCkSZqKnTc47yX9qFKY3M

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: realcodesiman

.agents/skills/builder-ui-i18n/SKILL.md

@@ -27,13 +27,13 @@ All user-facing strings must use translations. Do not hardcode labels,
 placeholders, button text, empty states, tab names, toasts, or dialog copy in
 builder UI.
 
-Primary files:
-
-- `apps/builder/messages/en.json`
-- `apps/builder/messages/vi.json`
+Source of truth: `apps/builder/messages/en.json`. **All 20 locale files in
+`apps/builder/messages/` must carry every key** — `apps/builder`'s own `lint` script is
+`i18n:check --source en --locales messages` (`apps/builder/package.json:11-12`), which runs
+in CI's Lint job. Adding a key to `en.json` + `vi.json` only will fail the parity check.
 
 Before adding keys, check existing `fields.*`, common actions, table labels, and
-feature namespaces. Add both English and Vietnamese values for new keys.
+feature namespaces.
 
 Typical component pattern:
 

.agents/skills/chatbotx-basecode/SKILL.md

@@ -14,42 +14,26 @@ not a replacement for reading adjacent code.
 
 ## Project Shape
 
-ChatbotX is a pnpm workspace + Turborepo monorepo.
+ChatbotX is a pnpm workspace + Turborepo monorepo. The authoritative layout table is
+**`AGENTS.md` → "Repository layout"** — read it there rather than trusting a second copy.
+To see what actually exists right now:
 
-```
-apps/
-  builder/     Next.js app: product UI, oRPC/OpenAPI, route handlers
-  worker/      BullMQ/Kafka background jobs
-  realtime/    PartyKit realtime server
-  cli/         chatbotx-cli
-  mcp-server/  MCP tools generated from OpenAPI
-
-packages/
-  business/       service layer and business orchestration
-  database/       Drizzle schema, relations, repositories, migrations
-  ui/             shared UI components
-  public-apis/    typed public API client
-  sdk/            integration contracts and shared schemas
-  worker-config/  queue names, job payloads, BullMQ queues
-  flow-config/    flow/node/step config schemas
-  ai, events, redis, kafka, filesystem, mail, imports, analytics, ...
-
-integrations/
-  messenger, whatsapp, zalo, tiktok, telegram, webchat, smtp, openai, google-sheets, ...
+```bash
+ls apps packages integrations
 ```
 
 ## Skill Router
 
-- Builder feature, page, action, query, or public route: use `feature-scaffold`.
-- oRPC or OpenAPI endpoint: use `orpc-api`.
-- Database schema, relations, migration, repository: use `drizzle-database`.
-- Service layer, app data-access boundary: use `business-data-access`.
-- UI component work, forms, tables, translations: use `builder-ui-i18n`.
-- Worker, BullMQ, Kafka, scheduled job: use `worker-development`.
-- Channel integration or webhook behavior: use `integration-channel`.
-- Flow step or state-based routing: use `flow-step-development`.
-- CLI, MCP server, generated public client: use `orpc-api`.
-- Dev server, build, lint, package management: use `turborepo-workflow`.
+The canonical task → skill routing table is **`CLAUDE.md` → "Skill → task mapping"**. Read
+it and pick the skill that matches the task; it lists every skill in `.agents/skills/`.
+
+Two routing notes that table does not spell out:
+
+- CLI, MCP server, and the generated public client all follow the public oRPC surface — use
+  `orpc-api`.
+- A broad request usually decomposes into several skills (e.g. a new feature with a table and
+  a queue = `feature-scaffold` + `drizzle-database` + `worker-development`). Read each before
+  writing that layer, not all of them up front.
 
 ## Basecode Scan Checklist
 

.agents/skills/contact-filter/SKILL.md

@@ -17,16 +17,26 @@ Lives in two packages:
 
 - **Frontend feature** — `apps/builder/src/features/contact-filter/` (Zod schemas,
   UI config, React components). Barrel: `index.ts`.
-- **Backend query builder** — `packages/database/src/queries/contact-filter.ts`
+- **Backend query builder** — `packages/database/src/queries/contact-filter/`
   (`@chatbotx.io/database/queries`). Shared by the builder app **and** the worker
-  so both resolve the same contacts.
+  so both resolve the same contacts. **`queries/contact-filter.ts` is now a one-line
+  re-export barrel** (`export * from "./contact-filter/index"`) — the real code is the
+  14-file directory beside it:
+
+  | Concern | File |
+  |---|---|
+  | Per-field dispatch (`buildConditionWhere`) | `contact-filter/index.ts:412` |
+  | Negation/NULL predicates, 24h window | `contact-filter/predicates.ts` (`COLUMN_NEGATION_OPERATORS:21`, `contactInboxInteractedWithin24hSQL:27`) |
+  | Operator inversion map | `contact-filter/field-value-predicates.ts` (`NEGATION_TO_POSITIVE:41`) |
+  | Relation EXISTS subqueries | `contact-filter/relation-sets.ts` (`RELATION_SET_FILTERS:76`, `buildRelationSetWhere:131`) |
+  | Custom / bot fields, CTWA, timezone, continent | `custom-field-predicates.ts`, `bot-field-predicates.ts`, `ctwa-retarget.ts`, `timezone.ts`, `continent.ts` |
 
 ## Architecture
 
 ```
 contactFilterFields enum (partials/contact.ts)     ← the field "universe" (~90)
         │
-CONTACT_FILTER_FIELD_DEFINITIONS (schema/definitions.ts)  ← 22 ACTIVE fields = single source of truth
+CONTACT_FILTER_FIELD_DEFINITIONS (schema/definitions.ts)  ← ~49 ACTIVE fields = single source of truth
         │  (each: { field, schemaKind, optionSource })
         ├──► Zod condition schemas  (schema/*.ts, via staticFieldFilter)
         └──► UI FieldConfig[]        (components/contact-filter-config.ts, getFieldConfigs)
@@ -60,15 +70,16 @@ Operators + form-field types: `packages/database/src/partials/custom-field.ts`
    - Zod validation: `STATIC_OPERATOR_RULES` in `schema/static-field-filter.ts`
    - UI enablement: `staticFieldRules` in `components/static-field-filter-config.ts`
 4. **Backend SQL** — add a `case` to `buildConditionWhere`
-   (`packages/database/src/queries/contact-filter.ts`). Without it the field
-   silently produces **no condition** (the `default: return {}` branch).
+   (`packages/database/src/queries/contact-filter/index.ts:412`; it takes
+   `(condition, context)`). Without it the field silently produces **no condition**
+   (the `default: return {}` branch).
 5. **Options / group** (if not `none`) — wire the option source in
    `use-contact-filter-configs.ts` / `contact-filter-config.ts`; group is assigned
    by `getContactFilterFieldGroup`.
 
 ## Where filter application lives
 
-`contactRepository.buildListWhere` (`packages/database/src/repositories/contact/list-where.ts`)
+`contactRepository.buildListWhere` (aliases `buildContactListWhere`, `packages/database/src/repositories/contact/list-where.ts:42`)
 is the one place `applyContactFilter` is called to build the where clause for
 a contacts list/count — used by both the builder (private RSC) and the public
 API, via `contactService.list`/`count` (`packages/business/src/contact/list.ts`).
@@ -78,10 +89,10 @@ split exists to prevent (see `.agents/rules/data-access.md`). The worker's
 `export-contacts.ts` still hand-builds its own where clause — a known
 follow-up, not a pattern to extend.
 
-## Backend query builder (`packages/database/src/queries/contact-filter.ts`)
+## Backend query builder (`packages/database/src/queries/contact-filter/`)
 
 - `applyContactFilter(criteria)` → maps `conditions` to `{ AND: [...] }` or
-  `{ OR: [...] }`; `buildConditionWhere(condition)` switches on `field`.
+  `{ OR: [...] }`; `buildConditionWhere(condition, context)` switches on `field`.
 - `buildContactWhere({ workspaceId, keyword?, contactFilter? })` → relational
   where for `contactModel`.
 - `buildContactInboxContactFilterSQL({ contactIdColumn, workspaceId, contactFilter })`
@@ -131,7 +142,7 @@ Messenger/WhatsApp subactions).
 
 ## Shared 24h window predicate
 
-`contactInboxInteractedWithin24hSQL()` (in `contact-filter.ts`) is the single
+`contactInboxInteractedWithin24hSQL()` (`contact-filter/predicates.ts:27`) is the single
 source for `lastIncomingMessageAt >= NOW() - INTERVAL '24 hours'`, used by:
 - the `interactedInLast24h` filter case (wrapped in a contact-level EXISTS), and
 - the broadcast audience (`apps/worker/src/schedule/handlers/prepare-broadcast.ts`)

.agents/skills/drizzle-database/SKILL.md

@@ -12,7 +12,9 @@ Package: `packages/database` (`@chatbotx.io/database`)
 
 ## Table Definition
 
-Tables use `pgTable` with `sharedColumns` spread for consistent `id`, `createdAt`, `updatedAt`:
+Tables use `pgTable` with `sharedColumns` spread for consistent `id`, `createdAt`,
+`updatedAt`. For a real workspace-scoped table to copy, read
+`packages/database/src/schema/minigame.ts` or any sibling in `schema/`; the shape is:
 
 ```typescript
 import { pgTable, text, index, uniqueIndex } from "drizzle-orm/pg-core"

.agents/skills/fb-comment-automation/SKILL.md

@@ -102,7 +102,8 @@ Read it before non-trivial changes. This skill is the quick map + the traps.
 3. Add the guard inside the loop in `processCommentAutomation`, **with a
    `logAutomationSkipped(..., reason)` before `continue`**.
 4. Surface the toggle in `apps/builder/src/features/fb-comments/components/fb-comment-form.tsx`
-   and add i18n keys to `apps/builder/messages/en.json` + `vi.json`.
+   and add i18n keys to **every** locale file in `apps/builder/messages/` (the i18n parity
+   check in `pnpm lint` fails on a missing key in any of the 20 locales).
 5. Extend `apps/worker/__tests__/comment-automation.test.ts`.
 
 ## Adding a new reply type (recipe)