@open-mercato/cli 0.4.7-main-1768da2e43 → 0.4.7

package/dist/agentic/shared/ai/skills/backend-ui-design/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: backend-ui-design
+description: Design and implement consistent backend/backoffice interfaces using @open-mercato/ui. Use when building admin pages, CRUD interfaces, data tables, forms, detail pages, or any backoffice UI.
+---
+
+# Backend UI Design
+
+Guide for creating consistent, production-grade backend interfaces using the `@open-mercato/ui` component library. All implementations must use existing components for visual and behavioral consistency.
+
+For complete component API reference, see `references/ui-components.md`.
+
+## Design Principles
+
+1. **Consistency First**: Every page should feel like part of the same application.
+2. **Component Reuse**: Never create custom implementations when a shared component exists.
+3. **Data Density**: Admin users need information-rich interfaces. Optimize for scanning.
+4. **Keyboard Navigation**: `Cmd/Ctrl+Enter` for primary actions, `Escape` to cancel.
+5. **Clear Hierarchy**: Page → Section → Content. Use `PageHeader`, `PageBody`, consistent spacing.
+
+## Required Component Library
+
+ALWAYS import from `@open-mercato/ui`.
+
+### Core Layout
+
+```tsx
+import { Page, PageHeader, PageBody } from '@open-mercato/ui/backend/Page'
+
+<Page>
+  <PageHeader>{/* Title, actions, breadcrumbs */}</PageHeader>
+  <PageBody>{/* Main content */}</PageBody>
+</Page>
+```
+
+### Data Display (Lists)
+
+Use `DataTable` for ALL tabular data. Never implement custom tables.
+
+```tsx
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import type { FilterDef } from '@open-mercato/ui/backend/FilterBar'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import { TruncatedCell } from '@open-mercato/ui/backend/TruncatedCell'
+import { BooleanIcon, EnumBadge } from '@open-mercato/ui/backend/ValueIcons'
+```
+
+Column patterns:
+- Text: `TruncatedCell` with `meta.maxWidth`
+- Boolean: `BooleanIcon`
+- Status/enum: `EnumBadge` with severity presets
+- Actions: `RowActions` for context menus
+
+### Forms
+
+Use `CrudForm` for ALL forms. Never build from scratch.
+
+```tsx
+import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
+```
+
+Field types: `text`, `textarea`, `number`, `email`, `password`, `select`, `multiselect`, `combobox`, `checkbox`, `switch`, `date`, `datetime`, `custom`.
+
+### Form Headers & Footers
+
+```tsx
+import { FormHeader, FormFooter, FormActionButtons, ActionsDropdown } from '@open-mercato/ui/backend/forms'
+```
+
+- **`FormHeader mode="edit"`** — compact header for CrudForm pages
+- **`FormHeader mode="detail"`** — large header for view/detail pages with entity type label, title, status badge, and Actions dropdown
+- **`FormFooter`** — footer wrapping `FormActionButtons`
+- **`ActionsDropdown`** — groups additional context actions (Convert, Send, Print). Delete is never inside the dropdown.
+
+### Dialogs
+
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
+
+// Dialog forms MUST use embedded={true}
+<CrudForm fields={fields} onSubmit={handleSubmit} embedded={true} submitLabel="Save" />
+```
+
+### Detail Pages
+
+```tsx
+import { DetailFieldsSection, LoadingMessage, ErrorMessage, TabEmptyState } from '@open-mercato/ui/backend/detail'
+import { NotesSection } from '@open-mercato/ui/backend/detail/NotesSection'
+import { TagsSection } from '@open-mercato/ui/backend/detail/TagsSection'
+import { CustomDataSection } from '@open-mercato/ui/backend/detail/CustomDataSection'
+```
+
+### Notifications
+
+```tsx
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+
+flash('Record saved successfully', 'success')
+flash('Failed to save record', 'error')
+flash('This action cannot be undone', 'warning')
+```
+
+NEVER use `alert()`, `console.log()`, or custom toast implementations.
+
+### Loading & Error States
+
+```tsx
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { DataLoader } from '@open-mercato/ui/primitives/DataLoader'
+import { Notice } from '@open-mercato/ui/primitives/Notice'
+import { ErrorNotice } from '@open-mercato/ui/primitives/ErrorNotice'
+import { EmptyState } from '@open-mercato/ui/backend/EmptyState'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+```
+
+### Primitives
+
+```tsx
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { Badge } from '@open-mercato/ui/primitives/badge'
+import { Switch } from '@open-mercato/ui/primitives/switch'
+import { SimpleTooltip } from '@open-mercato/ui/primitives/tooltip'
+```
+
+## API Integration
+
+```tsx
+import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+
+const handleCreate = async (values: FormValues) => {
+  const result = await createCrud<ResponseType>('module/resource', values)
+  if (result.ok) {
+    flash('Created successfully', 'success')
+    router.push(`/backend/module/${result.result.id}`)
+  }
+  return result
+}
+```
+
+## Custom Fields Integration
+
+```tsx
+import { useCustomFieldDefinitions } from '@open-mercato/ui/backend/utils/customFieldDefs'
+import { buildCustomFieldFormFields } from '@open-mercato/ui/backend/utils/customFieldForms'
+import { buildCustomFieldColumns } from '@open-mercato/ui/backend/utils/customFieldColumns'
+import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
+```
+
+## Implementation Checklist
+
+- [ ] Forms use `CrudForm` (not custom)
+- [ ] Tables use `DataTable` (not custom)
+- [ ] Notifications use `flash()` (not alert/toast)
+- [ ] Dialog forms have `embedded={true}`
+- [ ] Keyboard: `Cmd/Ctrl+Enter` (submit), `Escape` (cancel)
+- [ ] Loading states use `LoadingMessage` or `DataLoader`
+- [ ] Error states use `ErrorMessage`, `ErrorNotice`, or `Notice variant="error"`
+- [ ] Empty states use `EmptyState`
+- [ ] Column truncation uses `meta.truncate` and `meta.maxWidth`
+- [ ] Boolean values use `BooleanIcon`
+- [ ] Status/enum values use `EnumBadge`
+- [ ] Row actions use `RowActions` with stable `id` values
+- [ ] API calls use `apiCall`/`apiCallOrThrow` (not raw `fetch`)
+
+## Anti-Patterns
+
+1. Custom form implementations — use `CrudForm`
+2. Manual table markup — use `DataTable`
+3. Custom toast/notification — use `flash()`
+4. Inline styles — use Tailwind classes
+5. Hardcoded colors — use theme variables
+6. Missing loading states — every async operation needs feedback
+7. Missing error handling — every failure needs messaging
+8. Missing keyboard shortcuts — all dialogs need `Cmd+Enter` and `Escape`
+9. Custom truncation — use `TruncatedCell` with `meta.maxWidth`
+10. Direct `fetch()` — use `apiCall`/`apiCallOrThrow`
+
+## Visual Guidelines
+
+### Spacing
+- `p-4` for cards, `p-6` for page sections
+- `gap-4` or `gap-6` for flex/grid layouts
+- `space-y-4` or `space-y-6` for vertical rhythm
+
+### Colors
+- Use semantic colors from theme (no hardcoded hex)
+- Destructive: `variant="destructive"` on buttons
+- Status badges: `useSeverityPreset()`
+
+### Layout Patterns
+- **List pages**: FilterBar + DataTable + Pagination
+- **Detail pages**: Header + Tabs/Sections + Related data
+- **Create/Edit**: Full-page CrudForm or Dialog with embedded CrudForm
+- **Settings**: Grouped sections with inline editing

package/dist/agentic/shared/ai/skills/backend-ui-design/references/ui-components.md

@@ -0,0 +1,233 @@
+# UI Components Reference
+
+Complete reference of all available UI components in `@open-mercato/ui`.
+
+## Package Structure
+
+```
+@open-mercato/ui/
+├── primitives/          # Base UI components (shadcn-style)
+├── backend/             # Full-featured admin components
+├── frontend/            # Public-facing components
+└── theme/               # Theme and provider setup
+```
+
+## PRIMITIVES (`@open-mercato/ui/primitives/*`)
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| **Button** | `@open-mercato/ui/primitives/button` | Core button with variants (default, outline, ghost, destructive) |
+| **Input** | `@open-mercato/ui/primitives/input` | Text input field |
+| **Label** | `@open-mercato/ui/primitives/label` | Form label component |
+| **Textarea** | `@open-mercato/ui/primitives/textarea` | Multi-line text input |
+| **Dialog** | `@open-mercato/ui/primitives/dialog` | Modal dialog (Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter) |
+| **Tooltip** | `@open-mercato/ui/primitives/tooltip` | Hover tooltip + `SimpleTooltip` utility component |
+| **Table** | `@open-mercato/ui/primitives/table` | Table structure (Table, TableHeader, TableBody, TableRow, TableHead, TableCell) |
+| **Alert** | `@open-mercato/ui/primitives/alert` | Alert boxes (Alert, AlertTitle, AlertDescription) with variants |
+| **Badge** | `@open-mercato/ui/primitives/badge` | Small badge/tag labels with variants |
+| **Separator** | `@open-mercato/ui/primitives/separator` | Visual divider line |
+| **Switch** | `@open-mercato/ui/primitives/switch` | Toggle switch control |
+| **Spinner** | `@open-mercato/ui/primitives/spinner` | Loading spinner animation |
+| **Notice** | `@open-mercato/ui/primitives/Notice` | Contextual notice/hint with variants (`error`, `info`, `warning`) and optional `compact` mode |
+| **ErrorNotice** | `@open-mercato/ui/primitives/ErrorNotice` | Convenience wrapper around `<Notice variant="error">` with default title/message |
+| **DataLoader** | `@open-mercato/ui/primitives/DataLoader` | Loading state wrapper with spinner and optional skeleton |
+
+## BACKEND COMPONENTS (`@open-mercato/ui/backend/*`)
+
+### Core Layout & Navigation
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **AppShell** | `@open-mercato/ui/backend/AppShell` | Main application shell with sidebar, header, breadcrumbs | `navigation`, `user`, `children` |
+| **Page, PageHeader, PageBody** | `@open-mercato/ui/backend/Page` | Page layout containers | - |
+| **UserMenu** | `@open-mercato/ui/backend/UserMenu` | User profile dropdown with logout | `user`, `onLogout` |
+| **FlashMessages, flash** | `@open-mercato/ui/backend/FlashMessages` | Toast notifications. Use `flash(message, type)` programmatically | Type: 'success' \| 'error' \| 'warning' \| 'info' |
+
+### Data Display & Tables
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **DataTable** | `@open-mercato/ui/backend/DataTable` | Feature-rich table with sorting, filtering, pagination, export, perspectives | `columns`, `data`, `filters`, `pagination`, `perspective`, `onRowClick` |
+| **TruncatedCell** | `@open-mercato/ui/backend/TruncatedCell` | Table cell with text truncation and tooltip | `value`, `maxWidth` |
+| **EmptyState** | `@open-mercato/ui/backend/EmptyState` | Empty state placeholder | `title`, `description`, `action`, `icon` |
+| **RowActions** | `@open-mercato/ui/backend/RowActions` | Context menu for row actions | `items: {label, href?, onSelect?, destructive?}[]` |
+| **FilterBar** | `@open-mercato/ui/backend/FilterBar` | Search and filter UI bar | `filters`, `values`, `onApply`, `onClear` |
+| **ValueIcons** | `@open-mercato/ui/backend/ValueIcons` | `BooleanIcon`, `EnumBadge`, `useSeverityPreset()` | - |
+
+### Forms
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **CrudForm** | `@open-mercato/ui/backend/CrudForm` | Complete CRUD form with field registry, groups, custom fields, validation | `fields`, `groups`, `initialValues`, `onSubmit`, `schema`, `embedded`, `extraActions` |
+| **FormHeader** | `@open-mercato/ui/backend/forms` | Unified page header with `edit` mode (compact, for CrudForm) and `detail` mode (large title, entity type label, status badge, Actions dropdown) | `mode`, `backHref`, `title`, `actions`, `menuActions`, `onDelete`, `statusBadge` |
+| **FormFooter** | `@open-mercato/ui/backend/forms` | Form footer wrapping FormActionButtons with embedded/dialog layout awareness | `actions`, `embedded`, `className` |
+| **FormActionButtons** | `@open-mercato/ui/backend/forms` | Atomic button bar: [extraActions] [Delete] [Cancel] [Save]. Shared by header and footer. | `showDelete`, `onDelete`, `cancelHref`, `submit` |
+| **ActionsDropdown** | `@open-mercato/ui/backend/forms` | Dropdown menu for additional context actions (Convert, Send, Print). Only visible when items are provided. Delete is never inside the dropdown. | `items: ActionItem[]`, `label`, `size` |
+| **JsonBuilder** | `@open-mercato/ui/backend/JsonBuilder` | Interactive JSON editor with "Raw JSON" and "Builder" tabs | `value`, `onChange`, `disabled` |
+| **JsonDisplay** | `@open-mercato/ui/backend/JsonDisplay` | Read-only JSON viewer with expand/collapse | `data`, `title`, `maxInitialDepth`, `showCopy` |
+
+### Input Components (`@open-mercato/ui/backend/inputs/*`)
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **TagsInput** | `@open-mercato/ui/backend/inputs/TagsInput` | Multi-tag input with suggestions | `value`, `onChange`, `placeholder`, `suggestions` |
+| **ComboboxInput** | `@open-mercato/ui/backend/inputs/ComboboxInput` | Searchable dropdown (single value) | `value`, `onChange`, `options`, `placeholder` |
+| **PhoneNumberField** | `@open-mercato/ui/backend/inputs/PhoneNumberField` | Phone input with formatting | `value`, `onChange`, `checkDuplicate` |
+| **LookupSelect** | `@open-mercato/ui/backend/inputs/LookupSelect` | Async lookup/search select | `value`, `onChange`, `onSearch`, `renderItem` |
+| **SwitchableMarkdownInput** | `@open-mercato/ui/backend/inputs/SwitchableMarkdownInput` | Text/markdown toggle input | `value`, `onChange`, `placeholder` |
+
+### Detail Page Components (`@open-mercato/ui/backend/detail/*`)
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **DetailFieldsSection** | `@open-mercato/ui/backend/detail/DetailFieldsSection` | Entity field display with inline editing | `fields`, `entity`, `onUpdate` |
+| **InlineTextEditor** | `@open-mercato/ui/backend/detail/InlineEditors` | Click-to-edit text field | `value`, `onSave`, `label` |
+| **InlineMultilineEditor** | `@open-mercato/ui/backend/detail/InlineEditors` | Click-to-edit textarea | `value`, `onSave`, `label` |
+| **InlineSelectEditor** | `@open-mercato/ui/backend/detail/InlineEditors` | Click-to-edit select | `value`, `onSave`, `options`, `label` |
+| **NotesSection** | `@open-mercato/ui/backend/detail/NotesSection` | Notes/comments section with markdown | `notes`, `onAdd`, `onUpdate`, `onDelete` |
+| **TagsSection** | `@open-mercato/ui/backend/detail/TagsSection` | Tag management section | `tags`, `onAdd`, `onRemove`, `suggestions` |
+| **CustomDataSection** | `@open-mercato/ui/backend/detail/CustomDataSection` | Custom fields display | `data`, `fieldDefinitions` |
+| **LoadingMessage** | `@open-mercato/ui/backend/detail` | Loading state with spinner | `message` |
+| **ErrorMessage** | `@open-mercato/ui/backend/detail` | Error alert with action | `title`, `description`, `action` |
+| **TabEmptyState** | `@open-mercato/ui/backend/detail` | Empty state for tabs | `message`, `action` |
+
+## BACKEND UTILITIES (`@open-mercato/ui/backend/utils/*`)
+
+| Utility | Import Path | Purpose | Key Exports |
+|---------|-------------|---------|-------------|
+| **apiCall** | `@open-mercato/ui/backend/utils/apiCall` | HTTP client with auth | `apiCall`, `apiCallOrThrow`, `readApiResultOrThrow` |
+| **api** | `@open-mercato/ui/backend/utils/api` | Low-level API utils | `apiFetch` |
+| **crud** | `@open-mercato/ui/backend/utils/crud` | CRUD operation helpers | `createCrud`, `updateCrud`, `deleteCrud` |
+| **serverErrors** | `@open-mercato/ui/backend/utils/serverErrors` | Error mapping | `mapCrudServerErrorToFormErrors`, `createCrudFormError`, `raiseCrudError` |
+| **customFieldValues** | `@open-mercato/ui/backend/utils/customFieldValues` | Custom field value helpers | `collectCustomFieldValues`, `normalizeCustomFieldSubmitValue` |
+| **customFieldDefs** | `@open-mercato/ui/backend/utils/customFieldDefs` | Field definition fetching | `useCustomFieldDefinitions` |
+| **customFieldForms** | `@open-mercato/ui/backend/utils/customFieldForms` | Form field generation | `buildCustomFieldFormFields` |
+| **customFieldColumns** | `@open-mercato/ui/backend/utils/customFieldColumns` | Column builders | `buildCustomFieldColumns` |
+| **customFieldFilters** | `@open-mercato/ui/backend/utils/customFieldFilters` | Filter definitions | `useCustomFieldFilters` |
+
+## Common Usage Patterns
+
+### Flash Messages
+```tsx
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+
+flash('Record saved successfully', 'success')
+flash('Failed to save record', 'error')
+// Types: 'success' | 'error' | 'warning' | 'info'
+```
+
+### DataTable with Filters
+```tsx
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+
+const filters: FilterDef[] = [
+  { id: 'search', type: 'text', label: 'Search', placeholder: 'Search...' },
+  { id: 'status', type: 'select', label: 'Status', options: [...] },
+]
+
+<DataTable
+  title="Items"
+  columns={columns}
+  data={data}
+  filters={filters}
+  filterValues={filterValues}
+  onFiltersApply={handleFiltersApply}
+  onFiltersClear={handleFiltersClear}
+  pagination={{ page, pageSize, total, totalPages, onPageChange }}
+  onRowClick={(row) => router.push(`/items/${row.id}`)}
+/>
+```
+
+### CrudForm
+```tsx
+import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
+
+const fields: CrudField[] = [
+  { id: 'name', label: 'Name', type: 'text', required: true },
+  { id: 'description', label: 'Description', type: 'textarea' },
+  { id: 'status', label: 'Status', type: 'select', options: [...] },
+  { id: 'config', label: 'Config', type: 'custom', component: (props) => <JsonBuilder {...props} /> },
+]
+
+const groups: CrudFormGroup[] = [
+  { id: 'basic', title: 'Basic Info', column: 1, fields: ['name', 'description'] },
+  { id: 'settings', title: 'Settings', column: 1, fields: ['status', 'config'] },
+]
+
+<CrudForm
+  title="Create Item"
+  fields={fields}
+  groups={groups}
+  initialValues={{}}
+  onSubmit={handleSubmit}
+  submitLabel="Save"
+  embedded={true}  // For use inside dialogs
+  extraActions={<Button onClick={handleDelete}>Delete</Button>}
+/>
+```
+
+### Dialog with Form
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
+import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
+
+<Dialog open={isOpen} onOpenChange={onClose}>
+  <DialogContent className="sm:max-w-2xl [&_.grid]:!grid-cols-1">
+    <DialogHeader>
+      <DialogTitle>Edit Item</DialogTitle>
+    </DialogHeader>
+    <CrudForm
+      fields={fields}
+      groups={groups}
+      initialValues={initialValues}
+      onSubmit={handleSubmit}
+      embedded={true}
+      submitLabel="Save"
+    />
+  </DialogContent>
+</Dialog>
+```
+
+### Detail Page with Inline Editing
+```tsx
+import { DetailFieldsSection, LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+
+if (isLoading) return <LoadingMessage message="Loading..." />
+if (error) return <ErrorMessage title="Error" description={error.message} />
+
+<DetailFieldsSection
+  fields={[
+    { id: 'name', label: 'Name', type: 'text' },
+    { id: 'status', label: 'Status', type: 'select', options: [...] },
+  ]}
+  entity={entity}
+  onUpdate={handleUpdate}
+/>
+```
+
+### API Calls
+```tsx
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+
+// Generic API call
+const result = await apiCall<ResponseType>('/api/endpoint', { method: 'POST', body: JSON.stringify(data) })
+if (result.ok) {
+  // result.result contains the parsed JSON response
+}
+
+// CRUD operations
+const created = await createCrud<ItemType>('module/items', payload)
+const updated = await updateCrud<ItemType>('module/items', id, payload)
+const deleted = await deleteCrud('module/items', id)
+```
+
+## Important Notes
+
+1. **Always use `flash()` for notifications** - Don't use `alert()` or custom toast implementations
+2. **Use `CrudForm` for forms** - Provides consistent validation, field rendering, and keyboard shortcuts
+3. **Use `DataTable` for lists** - Includes filtering, sorting, pagination, export, and perspectives
+4. **Use `JsonBuilder` for JSON editing** - Provides both raw JSON and visual builder modes
+5. **Dialog forms need `embedded={true}`** - And add `[&_.grid]:!grid-cols-1` to DialogContent for single-column layout
+6. **Support Cmd/Ctrl+Enter and Escape** - All dialogs should support these keyboard shortcuts

package/dist/agentic/shared/ai/skills/code-review/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: code-review
+description: Review code changes for architecture, security, conventions, and quality compliance. Use when reviewing pull requests, code changes, or auditing code quality.
+---
+
+# Code Review
+
+Review code changes against Open Mercato architecture rules, security requirements, and quality standards.
+
+## Review Workflow
+
+1. **Scope**: Identify changed files. Classify by layer (entity, API route, validator, backend page, subscriber, worker, command, widget).
+2. **Gather context**: Read `AGENTS.md` for module conventions. Check `.ai/specs/` for active specs. Read `.ai/lessons.md` for known pitfalls.
+3. **CI/CD verification gate (MANDATORY)**: Run the checks below. Every gate MUST pass. See **CI/CD Gate** section.
+4. **Run checklist**: Apply rules from `references/review-checklist.md`. Flag violations with severity, file, and fix suggestion.
+5. **Test coverage**: Verify changed behavior is covered by tests. Flag missing coverage.
+6. **Cross-module impact**: If the change touches events, extensions, or widgets, verify consumers handle the contract correctly.
+7. **Output**: Produce the review report.
+
+## CI/CD Verification Gate (MANDATORY)
+
+**NEVER claim code is "ready to merge" without running these checks.** If any step fails, it MUST be fixed before the review can pass.
+
+| # | Command | What it checks | If it fails |
+|---|---------|----------------|-------------|
+| 1 | `yarn generate` | Module registries are up to date | Run it — it generates missing files |
+| 2 | `yarn typecheck` | TypeScript types are correct | Fix type errors |
+| 3 | `yarn test` | All unit tests pass | Fix failing tests |
+| 4 | `yarn build` | The app builds successfully | Fix build errors |
+
+**Rules**:
+- Steps 2 and 3 can run in parallel.
+- Every failure is a **Critical** finding — even if it appears unrelated to the current changes.
+- The review output MUST include actual pass/fail results. Do not assume — run and report.
+
+## Output Format
+
+```markdown
+# Code Review: {change description}
+
+## Summary
+{1-3 sentences: what the change does, overall assessment}
+
+## CI/CD Verification
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| `yarn generate` | PASS/FAIL | |
+| `yarn typecheck` | PASS/FAIL | |
+| `yarn test` | PASS/FAIL | |
+| `yarn build` | PASS/FAIL | |
+
+## Findings
+
+### Critical
+{Security, data integrity, tenant isolation violations}
+
+### High
+{Architecture violations, missing required exports}
+
+### Medium
+{Convention violations, suboptimal patterns}
+
+### Low
+{Suggestions, minor improvements}
+
+## Checklist
+{From references/review-checklist.md — mark [x] passing, [ ] failing with explanation}
+```
+
+Omit empty severity sections.
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Security vulnerability, cross-tenant leak, data corruption, missing auth | MUST fix before merge |
+| **High** | Architecture violation, missing required export, broken module contract | MUST fix before merge |
+| **Medium** | Convention violation, suboptimal pattern, missing best practice | Should fix |
+| **Low** | Style suggestion, minor improvement | Nice to have |
+
+## Quick Rule Reference
+
+### Architecture
+
+- **NO direct ORM relationships between modules** — use FK IDs, fetch separately
+- **Always filter by `organization_id`** for tenant-scoped entities
+- **Use DI (Awilix)** to inject services — never `new` directly
+- **NO direct module-to-module calls** for side effects — use events
+- **Cross-module data**: use extension entities + `data/extensions.ts`
+
+### Security
+
+- **Validate all inputs with zod** in `data/validators.ts`
+- **Use `findWithDecryption`** instead of raw `em.find`/`em.findOne`
+- **Hash passwords with bcryptjs (cost >= 10)** — never log credentials
+- **Every endpoint MUST declare auth guards** (`requireAuth`, `requireRoles`, `requireFeatures`)
+
+### Data Integrity
+
+- **Never hand-write migrations** — update entities, run `yarn db:generate`
+- **Validate migration scope** — autogenerated doesn't mean correct
+- **Workers/subscribers MUST be idempotent**
+- **Commands MUST be undoable** — include before/after snapshots
+
+### Naming
+
+- Modules: **plural, snake_case** (folders and `id`)
+- JS/TS identifiers: **camelCase**
+- Database: **snake_case**, table names plural
+- Standard columns: `id`, `created_at`, `updated_at`, `deleted_at`, `is_active`, `organization_id`
+
+### UI & HTTP
+
+- Forms: `CrudForm` — never custom
+- Tables: `DataTable` — never manual markup
+- Notifications: `flash()` — never `alert()` or custom toast
+- API calls: `apiCall`/`apiCallOrThrow` — never raw `fetch`
+- Dialogs: `Cmd/Ctrl+Enter` (submit), `Escape` (cancel)
+- `pageSize` MUST be <= 100
+
+### Code Quality
+
+- No `any` types — use zod + `z.infer`
+- No empty `catch` blocks
+- No one-letter variable names
+- Boolean parsing: use `parseBooleanToken`/`parseBooleanWithDefault`
+- Don't add docstrings/comments to code you didn't change
+
+## Review Heuristics
+
+1. **New files**: Check if `yarn generate` is needed. Verify auto-discovery paths.
+2. **Entity changes**: Check if `yarn db:generate` is needed. Look for missing tenant columns.
+3. **Migration sanity**: Inspect SQL content. Reject unrelated schema churn.
+4. **New API routes**: Verify `openApi` export, auth guards, zod validation, tenant filtering.
+5. **Event emitters**: Verify event is declared in `events.ts` with `as const`.
+6. **Commands**: Verify undoable, before/after snapshots.
+7. **UI changes**: Verify `CrudForm`/`DataTable`, `flash()`, keyboard shortcuts, loading/error states.
+8. **Test coverage**: Verify unit/integration tests cover new behavior.
+
+## Reference Materials
+
+- [Review Checklist](references/review-checklist.md)
+- [AGENTS.md](../../../AGENTS.md)

package/dist/agentic/shared/ai/skills/code-review/references/review-checklist.md

@@ -0,0 +1,77 @@
+# Code Review Checklist
+
+## 1. Architecture & Module Independence
+
+- [ ] No ORM relationships between modules — FK IDs only
+- [ ] No direct module-to-module function calls for side effects
+- [ ] DI (Awilix) used for service wiring
+- [ ] No cross-tenant data exposure
+- [ ] Code in correct location (`src/modules/<id>/`)
+
+## 2. Security
+
+- [ ] All inputs validated with zod in `data/validators.ts`
+- [ ] No `any` types
+- [ ] Auth guards on all endpoints (`requireAuth`, `requireRoles`, `requireFeatures`)
+- [ ] Passwords hashed with bcryptjs (cost >= 10)
+- [ ] No credentials logged or in error messages
+- [ ] `findWithDecryption` used instead of raw `em.find`/`em.findOne`
+- [ ] Tenant isolation: queries filter by `organization_id`
+
+## 3. Data Integrity & ORM
+
+- [ ] No hand-written migrations — entities updated, `yarn db:generate` run
+- [ ] Migration scope matches PR intent (no unrelated schema churn)
+- [ ] UUID primary keys with standard columns (`id`, `created_at`, `updated_at`)
+- [ ] Soft delete via `deleted_at` where applicable
+- [ ] Atomic transactions for multi-step writes
+
+## 4. API Routes
+
+- [ ] `openApi` exported for documentation
+- [ ] `metadata` exported with auth guards
+- [ ] Zod validation on request body
+- [ ] Tenant scoping in queries
+- [ ] `apiCall` used instead of raw `fetch`
+- [ ] `pageSize <= 100`
+
+## 5. Events & Commands
+
+- [ ] Events declared in `events.ts` with `createModuleEvents` and `as const`
+- [ ] Subscribers export `metadata` with `{ event, persistent?, id? }`
+- [ ] Workers export `metadata` with `{ queue, id?, concurrency? }`
+- [ ] All mutations implemented as commands with undo logic
+- [ ] Side effects outside `withAtomicFlush`
+
+## 6. UI & Backend Pages
+
+- [ ] Forms use `CrudForm` (not custom)
+- [ ] Tables use `DataTable` (not custom)
+- [ ] Notifications use `flash()` (not alert/toast)
+- [ ] Dialog forms have `embedded={true}`
+- [ ] Keyboard: `Cmd/Ctrl+Enter` submit, `Escape` cancel
+- [ ] Loading states: `LoadingMessage` or `DataLoader`
+- [ ] Error states: `ErrorMessage` or `ErrorNotice`
+- [ ] Empty states: `EmptyState`
+- [ ] `RowActions` items have stable `id` values
+- [ ] i18n: `useT()` client-side — no hardcoded strings
+
+## 7. Naming Conventions
+
+- [ ] Modules: plural, snake_case
+- [ ] JS/TS identifiers: camelCase
+- [ ] DB tables/columns: snake_case, plural table names
+- [ ] Feature naming: `<module>.<action>` (e.g. `inventory.view`)
+- [ ] Event naming: `module.entity.action` (singular entity, past tense)
+
+## 8. Anti-Patterns
+
+- [ ] No cross-module ORM links
+- [ ] No plural entity/command/event naming
+- [ ] No direct `fetch()` calls
+- [ ] No custom toast/notification implementations
+- [ ] No inline styles (use Tailwind)
+- [ ] No hardcoded colors (use theme)
+- [ ] No empty `catch` blocks
+- [ ] No `any` types
+- [ ] No missing loading/error states