merge: sync latest main

Author: nguyenvantruc92

.agents/rules/data-access.md

@@ -2,26 +2,45 @@
 
 ## Principle
 
-All database access **MUST** go through a **service** (`packages/business/`) or **repository** (`packages/database/src/repositories/`). No app-layer code (`apps/builder`, `apps/worker`) may import `db` from `@chatbotx.io/database/client` and execute queries directly.
+The chain is: **action / API handler → service (`packages/business/`) → repository (`packages/database/src/repositories/`) → DB**. No app-layer code (`apps/builder`, `apps/worker`, `integrations/`) may import `db` from `@chatbotx.io/database/client` and execute queries directly. The one exception is a **pure read with zero business logic** — see the carve-out below.
 
 ## Why
 
 - **Centralized logic:** Business rules, cache invalidation, and event emission stay in one place instead of being scattered across actions, queries, and workers.
 - **Testability:** Services and repositories can be mocked at a clear boundary.
 - **Sharding readiness:** The message table is already sharded; future tables may follow. Services and repositories abstract the routing logic away from callers.
-- **Consistency:** Multiple consumers (builder actions, worker handlers, oRPC endpoints) reuse the same data logic instead of duplicating it.
+- **Consistency:** Multiple consumers (builder actions, worker handlers, oRPC endpoints, public API tokens) reuse the same data logic instead of duplicating it.
+- **Public API / MCP surfaces need the same guarantees as the UI.** A workspace-token caller and a signed-in member hitting the same resource must run the same validation, cache invalidation, and event emission — which only happens if both call the same service method.
 
-## Allowed layers
+## Per-layer responsibilities
 
-| Layer | May import `db` directly? | Role |
-|-------|---------------------------|------|
-| `packages/database/src/repositories/*` | Yes | Raw query logic, shard routing |
-| `packages/business/src/*` | Yes | Business logic, cache, events, orchestrates repositories |
-| `apps/builder/src/features/*/actions/` | **No** | Call a service from `@chatbotx.io/business` |
-| `apps/builder/src/features/*/queries/` | **No** | Call a service or repository |
-| `apps/builder/src/features/*/api/` | **No** | Call a service or repository |
-| `apps/worker/src/**` | **No** | Call a service or repository |
-| `integrations/**` | **No** | Call a service or repository |
+| Layer | May import `db`? | Owns |
+|-------|---|------|
+| `packages/database/src/repositories/*` | Yes | Raw where-builders, joins, pagination, shard routing. **Never** cache invalidation, event emission, or validation. |
+| `packages/business/src/*` | Yes | Validation, orchestration across repositories, cache invalidation, events, audit, quota checks, optional `tx?: DatabaseClient` passthrough. **Never** imports from `apps/` or `integrations/`. |
+| `apps/builder/src/features/*/actions/` | **No** | Parse input → call a service method → map the result/error for the client. |
+| `apps/builder/src/features/*/queries/` | **No** | See the `.query.ts` contract below. |
+| `apps/builder/src/features/*/api/` | **No** | Resolve session context into plain params, call the same service method the private path uses. |
+| `apps/worker/src/**` | **No** | Call a service or repository. |
+| `integrations/**` | **No** | Call a service or repository. |
+
+**Repository-from-app-layer exception:** a pure read with zero business logic (no cache, no validation, no shape mapping beyond selecting columns) may call a repository directly from the app layer. This is the exception, not the default — reach for a service first, and only fall back to a bare repository call when there's genuinely nothing for a service to add.
+
+## The `.query.ts` file contract
+
+A file under `apps/builder/src/features/*/queries/` (`get-x.query.ts`, `list-x.queries.ts`) is a thin request adapter over one or more services. It:
+
+- **MAY** read session context (current user, member permissions) and turn it into plain params (`accessScope`, `canViewEmailAndPhone`, `restrictToAssignedUserId`, …) passed into a service call.
+- **MAY** map a service result onto the builder's response/UI shape.
+- **MAY** compose several services for one screen.
+- **MUST NOT** hold where-builders, joins, pagination logic, count/caching strategy, or anything a worker or the public API would also need — that belongs in the service (orchestration) or repository (raw query), not duplicated per caller.
+- **MUST NOT** import `db` — call a service (or, for the pure-read exception above, a repository).
+
+**A session-free read is called straight from the handler; it needs no query file at all.** Only add a `.query.ts` file when there is real builder-side session-context work (permission scope resolution, response shaping) to adapt.
+
+## Public API and private paths share one service method
+
+The public API (workspace-token) handler and the private action/query adapter for the same operation **must call the same service method**. Only the app layer resolves the caller's permission scope (member permissions vs. an unscoped token) and passes it into the service as plain data (`scope`/`accessScope`) — the service itself never knows whether the caller was a signed-in member or a token. Do not write a second, parallel implementation of the same logic for the public path "because it's simpler" — that is exactly the duplication this layering exists to prevent.
 
 ## How to add new data access
 
@@ -30,7 +49,7 @@ All database access **MUST** go through a **service** (`packages/business/`) or
    - `packages/business/src/<domain>/service.ts` — class extending `BaseService`
    - `packages/business/src/<domain>/index.ts` — re-export the singleton
    - Add the export to `packages/business/src/index.ts`
-3. **For pure query helpers** that don't carry business logic (e.g., shard-routed reads), a repository in `packages/database/src/repositories/<domain>/` is acceptable.
+3. **For pure query helpers** that don't carry business logic (e.g., shard-routed reads, a where-builder shared across callers), a repository in `packages/database/src/repositories/<domain>/` is acceptable — but the service is still the thing the app layer calls; the app layer reaches the repository directly only under the pure-read exception above.
 4. **Services accept an optional `tx?: DatabaseClient`** parameter so callers can pass a transaction handle.
 
 ## Existing exceptions
@@ -41,7 +60,9 @@ Many older features still import `db` directly in actions and queries. These are
 
 Before marking a task done:
 
-- [ ] No new `import { db } from "@chatbotx.io/database/client"` in `apps/` or `integrations/`
+- [ ] No new `import { db } from "@chatbotx.io/database/client"` in `apps/` or `integrations/` (outside the pure-read repository exception)
 - [ ] No new `import ... from "@chatbotx.io/database/schema"` with direct query execution in `apps/` or `integrations/`
 - [ ] All DB mutations go through a service method
-- [ ] All DB reads go through a service or repository method
+- [ ] All DB reads go through a service (or, for a pure read with zero business logic, a repository)
+- [ ] A public API handler and its private-path equivalent call the same service method, with only the caller's scope differing
+- [ ] `.query.ts` files hold no where-builders, pagination, or count logic — that lives in the service/repository

.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/business-data-access/SKILL.md

@@ -12,6 +12,15 @@ description: >-
 Use this skill whenever code outside `packages/business` or
 `packages/database/src/repositories` needs database-backed behavior.
 
+## The chain
+
+`action | API handler → service (packages/business) → repository
+(packages/database/src/repositories) → DB`. This is the wording to use —
+never "service **or** repository" as if they were interchangeable
+alternatives for the app layer. The app layer calls a service; the service
+may call a repository. See `.agents/rules/data-access.md` for the full rule
+and the per-layer responsibility table.
+
 ## Boundary Rule
 
 Do not add direct database imports in:
@@ -20,23 +29,44 @@ Do not add direct database imports in:
 - `apps/worker`
 - `integrations`
 
-These layers call services from `@chatbotx.io/business` or repositories from
-`@chatbotx.io/database/repositories`. Legacy direct `db` imports are exceptions,
-not examples to copy.
+These layers call services from `@chatbotx.io/business`. Legacy direct `db`
+imports are exceptions, not examples to copy. The one narrow exception is a
+**pure read with zero business logic** — no cache, no validation, no
+cross-table composition — which may call a repository from
+`@chatbotx.io/database/repositories` directly; this is the exception, not
+the default, so reach for a service first.
 
 Allowed direct `db` usage:
 
 - `packages/business/src/**`
 - `packages/database/src/repositories/**`
 
+## Service responsibilities
+
+A service owns:
+
+- Input validation and authorization-adjacent checks (e.g. quota, ownership).
+- Orchestration across one or more repositories.
+- Cache invalidation (`this.invalidateCacheTags(...)`).
+- Event emission (`emit*` from `@chatbotx.io/events`, `@chatbotx.io/event-bus`).
+- Audit records (`this.audit(...)`).
+- An optional `tx?: DatabaseClient` passthrough so callers can compose it into
+  their own transaction.
+- **Never** imports from `apps/` or `integrations/` — a service has no idea
+  who is calling it (a builder action, a worker job, a public API handler).
+
 ## Choosing Service vs Repository
 
 Use a business service when the method has business semantics, authorization
 adjacent constraints, cache invalidation, event emission, composition across
 tables, or is reused by app and worker code.
 
 Use a repository when the method is a low-level persistence concern such as
-shard routing, specialized pagination, or reusable raw query mechanics.
+shard routing, specialized pagination, a where-builder shared across callers,
+or reusable raw query mechanics. **Repositories are raw only** — no cache
+invalidation, no event emission, no validation. If a query needs any of
+those, it belongs behind a service method that calls the repository, not in
+the repository itself.
 
 ## Service Pattern
 
@@ -101,16 +131,72 @@ Use the `drizzle-database` skill for schema, relation, and migration work.
 
 ## App Layer Usage
 
-Builder feature queries/actions should call services:
+### Session-free read: no query file needed
+
+`tagService.list` needs nothing from the request session — the builder calls
+it directly from wherever it's needed (a page, another query), with no
+`.query.ts` adapter in between:
 
 ```typescript
 import { tagService } from "@chatbotx.io/business"
 
-export const listTags = async (params: { workspaceId: string }) => {
-  return tagService.list({ workspaceId: params.workspaceId })
+const { data } = await tagService.list({ workspaceId })
+```
+
+If you find yourself writing a one-line pass-through query file that only
+forwards its arguments to a service, delete the file and call the service
+directly instead.
+
+### Session-context read: a thin `.query.ts` adapter
+
+`get-contact.query.ts` needs the current member's permission scope before it
+can call the service — that's the shape a query file exists for:
+
+```typescript
+// apps/builder/src/features/contacts/queries/get-contact.query.ts
+import { contactService } from "@chatbotx.io/business"
+import { requireContactPermissionScope } from "../permissions"
+
+export async function getContact(input: { workspaceId: string; id: string }) {
+  const accessScope = await requireContactPermissionScope(input.workspaceId)
+  const contact = await contactService.findDetailOrFail({
+    workspaceId: input.workspaceId,
+    id: input.id,
+    accessScope,
+  })
+  return maskIfNeeded(contact, accessScope)
+}
+```
+
+The query file's only job is: resolve session context → plain params → call
+the service → shape the response. It holds no where-builders, no pagination,
+no count strategy — see `.agents/rules/data-access.md` for the full
+`.query.ts` contract.
+
+### Public API and private paths share one service method
+
+An unscoped workspace-token caller and a signed-in member both resolve to
+`contactService.list({ ...input, scope })` — the only difference is what
+`scope` the app layer resolved (`undefined` for the token, a permission
+scope for the member):
+
+```typescript
+// Public API handler (workspace token — unscoped)
+.handler(async ({ context, input }) =>
+  await contactService.list({ ...input, workspaceId: context.workspace.id }),
+)
+
+// Private query adapter (signed-in member — scoped)
+export async function listContacts(input: ListContactsRequest) {
+  const scope = await requireContactPermissionScope(input.workspaceId)
+  return await contactService.list({ ...input, scope })
 }
 ```
 
+Never write a second implementation of the list/count/filter logic for the
+public path — both callers must converge on the same service method so a bug
+fix or a new filter only has to happen once.
+
 Workers and integrations follow the same boundary.
 
 ## Verification

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

@@ -14,53 +14,38 @@ 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 `public-api-tooling`.
-- 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
 
 1. Read the nearest `package.json`, route/module files, and sibling features.
-2. Identify the owning layer before editing:
-   - UI/app orchestration: `apps/builder`
-   - business rules: `packages/business`
-   - raw database queries: `packages/database/src/repositories`
+2. Identify the owning layer before editing — the chain is
+   `action | API handler → service → repository → DB`:
+   - UI/app orchestration (calls a service, never `db`): `apps/builder`
+   - business rules, cache invalidation, events (calls a repository): `packages/business`
+   - raw database queries, shard routing: `packages/database/src/repositories`
    - schema/migrations: `packages/database`
-   - async processing: `apps/worker` + `packages/worker-config`
-   - external channel protocol: `integrations/<channel>`
+   - async processing (calls a service, never `db`): `apps/worker` + `packages/worker-config`
+   - external channel protocol (calls a service, never `db`): `integrations/<channel>`
 3. Search for a similar feature and mirror naming, imports, error handling, and tests.
 4. Check `.agents/rules/*` for local invariants, especially data access and git.
 5. Keep changes scoped to the user request; do not refactor legacy exceptions unless required.