@tailor-platform/erp-kit 0.6.0 → 0.8.0

package/skills/erp-kit-app-6-impl-frontend/references/detail-view.md

@@ -0,0 +1,255 @@
+# DetailView Pattern
+
+## File Structure
+
+```bash
+[id]/
+  page.tsx                          # route entry — fetches data, composes fragments
+  components/
+    <entity>-detail.tsx             # DescriptionCard with field definitions
+    <entity>-actions.tsx            # ActionPanel with mutation actions
+```
+
+## page.tsx
+
+```tsx
+import {
+  Layout,
+  useParams,
+  type AppShellPageProps,
+} from "@tailor-platform/app-shell";
+import { useQuery } from "urql";
+import { UserDetail, UserDetailFragment } from "./components/user-detail";
+import { UserActions, UserActionsFragment } from "./components/user-actions";
+import { graphql } from "@/graphql";
+import { ErrorFallback } from "@/components/composed/error-fallback";
+import { Loading } from "@/components/composed/loading";
+
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserDetail
+        ...UserActions
+      }
+    }
+  `,
+  [UserDetailFragment, UserActionsFragment],
+);
+
+const UserPage = () => {
+  const { id } = useParams();
+  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
+    query: UserQuery,
+    variables: { id: id! },
+  });
+
+  if (fetching) return <Loading />;
+  if (error || !data?.user)
+    return (
+      <ErrorFallback
+        title="Failed to load user"
+        message="An error occurred while fetching the user details."
+        onReset={() => reexecuteQuery({ requestPolicy: "network-only" })}
+      />
+    );
+
+  return (
+    <Layout>
+      <Layout.Header title="User Detail" />
+      <Layout.Column>
+        <UserDetail user={data.user} />
+      </Layout.Column>
+      <Layout.Column>
+        <UserActions user={data.user} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+
+UserPage.appShellPageProps = {
+  meta: { title: "User Detail" },
+} satisfies AppShellPageProps;
+export default UserPage;
+```
+
+## `<entity>-detail.tsx` — DescriptionCard
+
+```tsx
+import { DescriptionCard } from "@tailor-platform/app-shell";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+
+export const UserDetailFragment = graphql(`
+  fragment UserDetail on User {
+    id
+    name
+    email
+    status
+    createdAt
+    updatedAt
+  }
+`);
+
+export const UserDetail = ({
+  user: userFragment,
+}: {
+  user: FragmentOf<typeof UserDetailFragment>;
+}) => {
+  const user = readFragment(UserDetailFragment, userFragment);
+  return (
+    <DescriptionCard
+      data={user}
+      title="User Information"
+      columns={3}
+      fields={[
+        { key: "name", label: "Name" },
+        { key: "email", label: "Email", meta: { copyable: true } },
+        {
+          key: "status",
+          label: "Status",
+          type: "badge",
+          meta: {
+            badgeVariantMap: {
+              ACTIVE: "success",
+              PENDING: "warning",
+              INACTIVE: "neutral",
+            },
+          },
+        },
+        { type: "divider" },
+        {
+          key: "createdAt",
+          label: "Created At",
+          type: "date",
+          meta: { dateFormat: "medium" },
+        },
+        {
+          key: "updatedAt",
+          label: "Updated At",
+          type: "date",
+          meta: { dateFormat: "relative" },
+        },
+      ]}
+    />
+  );
+};
+```
+
+### DescriptionCard Field Types
+
+| `type`      | Description                       | `meta` options                                                               |
+| ----------- | --------------------------------- | ---------------------------------------------------------------------------- |
+| (omitted)   | Plain text                        | `copyable: true`                                                             |
+| `"badge"`   | Status badge with variant mapping | `badgeVariantMap: { VALUE: "success" \| "warning" \| "neutral" \| "error" }` |
+| `"date"`    | Formatted date/time               | `dateFormat: "short" \| "medium" \| "long" \| "relative"`                    |
+| `"divider"` | Horizontal rule                   | —                                                                            |
+
+### Multiple DescriptionCards
+
+When an entity has a logically distinct secondary collection (e.g. taxonomy assignments, related items), render it as a second `DescriptionCard` stacked below the primary one.
+
+## `<entity>-actions.tsx` — ActionPanel
+
+```tsx
+import { ActionPanel, useNavigate } from "@tailor-platform/app-shell";
+import { useMutation } from "urql";
+import { Pencil, UserX, UserCheck } from "lucide-react";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+import { useToast } from "@/hooks/use-toast";
+
+const DeactivateUserMutation = graphql(`
+  mutation DeactivateUser($userId: String!) {
+    deactivateUser(userId: $userId) {
+      id
+      status
+    }
+  }
+`);
+
+export const UserActionsFragment = graphql(`
+  fragment UserActions on User {
+    id
+    status
+  }
+`);
+
+export const UserActions = ({
+  user: userFragment,
+}: {
+  user: FragmentOf<typeof UserActionsFragment>;
+}) => {
+  const user = readFragment(UserActionsFragment, userFragment);
+  const navigate = useNavigate();
+  const toast = useToast();
+  const [{ fetching: deactivating }, deactivateUser] = useMutation(
+    DeactivateUserMutation,
+  );
+
+  return (
+    <ActionPanel
+      title="Actions"
+      actions={[
+        {
+          key: "edit",
+          label: "Edit User",
+          icon: <Pencil />,
+          onClick: () => navigate("edit"),
+        },
+        ...(user.status === "ACTIVE"
+          ? [
+              {
+                key: "deactivate",
+                label: "Deactivate User",
+                icon: <UserX />,
+                loading: deactivating,
+                onClick: () =>
+                  deactivateUser({ userId: user.id }).then((result) => {
+                    if (result.error) {
+                      toast.error(result.error);
+                      return;
+                    }
+                    toast.success("User deactivated successfully");
+                  }),
+              },
+            ]
+          : []),
+      ]}
+    />
+  );
+};
+```
+
+### Error Handling in Actions
+
+Always handle mutation results with `useToast`:
+
+```tsx
+import { useToast } from "@/hooks/use-toast";
+
+const toast = useToast();
+
+// In onClick:
+onClick: () =>
+  someMutation({ ... }).then((result) => {
+    if (result.error) {
+      toast.error(result.error); // accepts CombinedError directly
+      return;
+    }
+    toast.success("Action completed successfully");
+  }),
+```
+
+- `toast.error(result.error)` accepts `CombinedError` from urql directly — no manual message extraction needed
+- `toast.success(message)` for successful operations
+- Import from `@/hooks/use-toast`, not from `@tailor-platform/app-shell` directly (ESLint enforced)
+
+### ActionItem Fields
+
+| Field      | Type                          | Description                            |
+| ---------- | ----------------------------- | -------------------------------------- |
+| `key`      | `string`                      | React key                              |
+| `label`    | `string`                      | Visible row label                      |
+| `icon`     | `ReactNode`                   | Icon from `lucide-react`               |
+| `onClick`  | `() => void \| Promise<void>` | Use `useNavigate()` for routing        |
+| `disabled` | `boolean?`                    | Disable the row                        |
+| `loading`  | `boolean?`                    | Show spinner, make row non-interactive |

package/skills/erp-kit-app-6-impl-frontend/references/pages.md

@@ -27,11 +27,7 @@ Key points:
 
 ### DetailView
 
-Key points:
-
-- Two-column `Layout`: detail on left, actions on right
-- `useParams()` to get entity ID from route
-- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields. Refer to existing examples in the codebase for props and field type usage.
+See **[detail-view.md](detail-view.md)** for the full pattern including `DescriptionCard` field types and `ActionPanel` usage.
 
 ### Form Pattern
 

package/skills/erp-kit-app-7-impl-review/SKILL.md

@@ -7,6 +7,18 @@ description: Review implementation parity between documentation and code for app
 
 Review **implementation consistency** between Tier 3-4 documentation and actual backend/frontend code.
 
+## Progress Logging
+
+Log to the audit trail at every checkpoint. See [erp-kit-app-shared/references/progress-protocol.md](../erp-kit-app-shared/references/progress-protocol.md) for the full protocol.
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+Required checkpoints: `step.start` (on invocation), `decision` (on user choices), `agent.dispatch`/`agent.result` (on subagent lifecycle), `artifact.create` (on file writes), `validation` (on `erp-kit app check` or build commands), `step.complete` (on finish), `error` (on failures).
+
+Bundle all conversation since the last checkpoint into the `conversation` array. Use your session ID as `sessionId`. Use the user's original prompt as `prompt`.
+
 ## When to Use
 
 - After backend and frontend implementation, verify code matches documentation
@@ -24,6 +36,7 @@ Define shared context for all agents:
 - `BACKEND_RESOLVERS`: glob `<APP_ROOT>/backend/src/resolvers/*.ts`
 - `BACKEND_EXECUTORS`: glob `<APP_ROOT>/backend/executors/*.ts`
 - `BACKEND_MODULES`: `<APP_ROOT>/backend/src/modules.ts`
+- `BACKEND_MODULES_DB`: `<APP_ROOT>/backend/src/modules-db.ts`
 - `BACKEND_CONFIG`: `<APP_ROOT>/backend/tailor.config.ts`
 - `FRONTEND_PAGES`: glob `<APP_ROOT>/frontend/src/app/(main)/**/*.tsx`
 
@@ -41,7 +54,7 @@ All review agents are read-only — no shared-file conflict risk.
 | ----- | -------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------ |
 | A     | [references/resolver-doc-code-parity.md](references/resolver-doc-code-parity.md) | One per resolver   | Single RESOLVER_DOC + matching BACKEND_RESOLVER + BACKEND_EXECUTOR |
 | B     | [references/screen-doc-code-parity.md](references/screen-doc-code-parity.md)     | One per screen     | Single SCREEN_DOC + matching FRONTEND_PAGE directory         |
-| C     | [references/module-wiring-parity.md](references/module-wiring-parity.md)         | One per resolver   | Single RESOLVER_DOC + BACKEND_MODULES + BACKEND_CONFIG       |
+| C     | [references/module-wiring-parity.md](references/module-wiring-parity.md)         | One per resolver   | Single RESOLVER_DOC + BACKEND_MODULES + BACKEND_MODULES_DB + BACKEND_CONFIG |
 | D     | Build verification (inline)                                                      | One global agent   | All source paths                                             |
 
 With R resolvers and S screens, this produces R + S + R + 1 parallel agents.
@@ -60,7 +73,7 @@ Run build checks and source-doc sync check inline:
 ```bash
 cd <APP_ROOT>/backend && pnpm lint && pnpm typecheck
 cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
-erp-kit app sync-check -p <APP_ROOT>/..
+npx erp-kit app sync-check -p <APP_ROOT>
 ```
 
 Report pass/fail for each check. `sync-check` detects missing resolver implementations, orphaned docs, and story doc ↔ integration test case mismatches, so groups A-C agents can skip file-existence checks and focus on content parity.
@@ -107,7 +120,7 @@ Render the aggregated results as markdown:
 
 ### 3. Module Wiring Consistency
 
-| Resolver | Required Module | Wired in modules.ts | Config Reference | Gap |
+| Resolver | Required Module | Wired in modules.ts / modules-db.ts | Config Reference | Gap |
 | -------- | --------------- | ------------------- | ---------------- | --- |
 
 (Populated from agent 3 gaps)

package/skills/erp-kit-app-7-impl-review/references/module-wiring-parity.md

@@ -5,12 +5,13 @@
 App: {{APP_NAME}}
 Resolver docs: {{RESOLVER_DOCS}}
 Backend modules file: {{BACKEND_MODULES}}
+Backend modules-db file: {{BACKEND_MODULES_DB}}
 Backend config file: {{BACKEND_CONFIG}}
 
 ## Instructions
 
 1. Read ALL resolver docs at the paths above
-2. Read the modules file (`src/modules.ts`)
+2. Read the modules file (`src/modules.ts`) and the modules-db file (`src/modules-db.ts`)
 3. Read the config file (`tailor.config.ts`)
 4. Verify all required modules are wired and configured
 5. Return results as JSON per the Output Format section
@@ -22,13 +23,18 @@ From each resolver doc, extract:
 - Module it depends on (which `defineXxxModule` it needs)
 - Commands it calls (which module command functions)
 
-## Extraction: modules.ts
+## Extraction: modules.ts and modules-db.ts
 
-From the modules file, extract:
+From `modules.ts`, extract:
 
 - All `defineXxxModule()` calls
 - Inter-module dependency wiring (e.g., primitives passed to item-management)
-- Exported `db`, `commands`, and `executors`
+- Exported module objects (`umModules`, `imModules`, etc.)
+
+From `modules-db.ts`, extract:
+
+- Individual DB table exports (destructured from module objects)
+- This file must NOT be imported by resolvers
 
 ## Extraction: tailor.config.ts
 
@@ -43,7 +49,7 @@ From the config file, extract:
 
 | Check ID             | Question                                                         |
 | -------------------- | ---------------------------------------------------------------- |
-| module_wired         | Is every module referenced by resolvers wired in modules.ts?     |
+| module_wired         | Is every module referenced by resolvers wired in modules.ts and exported in modules-db.ts? |
 | dependency_order     | Are inter-module dependencies passed correctly?                  |
 | exports_complete     | Are db, commands, and executors all exported?                    |
 | config_resolver_glob | Does the resolver glob in config cover all resolver directories? |
@@ -54,14 +60,14 @@ From the config file, extract:
 ### How to Check
 
 1. Build a set of required modules from resolver docs
-2. Check each required module appears as a `defineXxxModule()` call in modules.ts
+2. Check each required module appears as a `defineXxxModule()` call in modules.ts and its DB types are exported in modules-db.ts
 3. Verify dependency wiring (e.g., if item-management resolvers exist, primitives must be wired into it)
-4. Check tailor.config.ts resolver glob pattern covers all module resolver directories
+4. Check tailor.config.ts db.files references modules-db.ts and resolver glob pattern covers all resolver directories
 5. Verify auth is configured if any resolver requires authentication
 
 ## Common Gap Patterns
 
-- **Missing module**: Resolver references a module not wired in modules.ts
+- **Missing module**: Resolver references a module not wired in modules.ts or not exported in modules-db.ts
 - **Missing dependency**: Module wired but not given required dependencies
 - **Glob mismatch**: Config resolver glob doesn't cover a module's resolvers directory
 - **Missing auth**: Resolvers exist but no auth configured

package/skills/erp-kit-app-shared/references/progress-protocol.md

@@ -0,0 +1,77 @@
+# Progress Logging Protocol
+
+## Overview
+
+All `erp-kit-app-*` skills log to an append-only audit trail at `.erp-kit/progress.jsonl`. This records conversations, decisions, and agent activity across sessions.
+
+The log is NOT the source of truth for progress — the produced docs and code are. The log answers "what happened and why."
+
+## CLI Commands
+
+### Log an event
+
+```bash
+npx erp-kit app progress log --json '<ProgressInput JSON>'
+```
+
+### Validate without writing
+
+```bash
+npx erp-kit app progress log --dry-run --json '<ProgressInput JSON>'
+```
+
+### Get the JSON Schema
+
+```bash
+npx erp-kit app progress schema
+```
+
+## When to Log
+
+Log at natural checkpoints — moments where the skill is already pausing to take action. Bundle all conversation since the last checkpoint into the `conversation` array.
+
+| Checkpoint | Event type | When |
+|---|---|---|
+| Skill invocation | `step.start` | First thing after skill is invoked |
+| User decision | `decision` | User approves, corrects, or chooses |
+| Subagent launch | `agent.dispatch` | Before dispatching a subagent |
+| Subagent return | `agent.result` | After subagent completes |
+| File write | `artifact.create` | After creating/modifying/deleting a file |
+| Validation | `validation` | After running `erp-kit app check`, build, lint, etc. |
+| Skill completion | `step.complete` | Last thing before skill finishes |
+| Failure | `error` | When something fails |
+| Free-form | `note` | Anything else (e.g., session pause) |
+
+## Entry Format
+
+Every entry requires:
+
+- `v` — Schema version, always `1`
+- `sessionId` — Your AI session ID
+- `prompt` — The user's original prompt (the request that triggered this skill)
+- `event` — Event type from the table above
+- `data` — Event-specific payload (see schema)
+- `conversation` — Array of `{role, message}` since last checkpoint (optional, defaults to `[]`)
+
+The CLI auto-adds `timestamp` and `git` context.
+
+## Example
+
+```bash
+npx erp-kit app progress log --json '{
+  "v": 1,
+  "sessionId": "claude-abc123",
+  "prompt": "Create screens for manufacturing flows",
+  "event": "decision",
+  "conversation": [
+    {"role": "agent", "message": "Flat list or collapsible tree for BOM?"},
+    {"role": "user", "message": "Collapsible tree"}
+  ],
+  "data": {
+    "question": "BOM list view style",
+    "choice": "Collapsible tree",
+    "alternatives": ["Flat list with indent"],
+    "rationale": "Better UX for multi-level BOMs"
+  }
+}'
+```

package/skills/erp-kit-mock-scenario/SKILL.md

@@ -112,7 +112,7 @@ Create `mocks/{provider}/{scenario}/README.md` with:
 ### Step 5: Validate
 
 ```bash
-erp-kit mock validate
+npx erp-kit mock validate
 ```
 
 Fix any failures before finishing.

package/skills/erp-kit-module-1-requirements/SKILL.md

@@ -70,7 +70,7 @@ The final feature set becomes the union of all `Include` features. Proceed with
 First, scaffold the module if it doesn't exist:
 
 ```bash
-erp-kit module init <module-name> <MODULES_ROOT>/<module-name>
+npx erp-kit module init <module-name> <MODULES_ROOT>/<module-name>
 ```
 
 Then, for each `Include` feature, launch an Agent:

package/skills/erp-kit-module-3-plan/SKILL.md

@@ -44,9 +44,9 @@ Produce consolidated plan:
 Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
 
 ```bash
-erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
 ```
 
 Fill in the scaffolded docs with details from the extraction in Step 2.

package/skills/erp-kit-module-3-update-plan/SKILL.md

@@ -78,9 +78,9 @@ For each item in the fix plan:
 Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
 
 ```bash
-erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
-erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+npx erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
 ```
 
 Populate the new docs using the extraction rules from:

package/skills/erp-kit-module-5-impl/SKILL.md

@@ -37,7 +37,7 @@ Verify at least one doc type exists. If none, stop with: "No docs found for modu
 Run generation first to create `.generated.ts` files (error classes, permission definitions, command/query shells) before implementing any code:
 
 ```bash
-erp-kit module generate code -p <MODULES_ROOT>/<module>
+npx erp-kit module generate code -p <MODULES_ROOT>/<module>
 ```
 
 Never edit these generated files.

package/skills/erp-kit-module-6-impl-review/SKILL.md

@@ -33,42 +33,39 @@ Verify at least `MODEL_DOCS`, `COMMAND_DOCS`, or `QUERY_DOCS` is non-empty. If n
 
 ## Step 2: Dispatch Agents (parallelize ALL agents in a single message)
 
-Split each parity check into its own agent, then further split by file batches when there are many files. Target **~5 agents per domain** (model, command, query) for maximum parallelism. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.
+Split checks into agents by **domain + file batch**, not by check type. Command checks (C-1, C-2, C-3) run together in one agent per batch; query checks (Q-1, Q-2, Q-3) run together in one agent per batch. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.
 
-If a doc or code directory is empty, skip that agent entirely.
+If a doc or code directory is empty, skip that domain entirely.
 
 ### Splitting Strategy
 
-1. **Each parity check type = separate agent** (never combine different check types in one agent)
-2. **File batching**: If a check has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent running the same check type on a subset of files.
+1. **Domain grouping**: C-1 + C-2 + C-3 in the same agent. Q-1 + Q-2 + Q-3 in the same agent. M-1 is its own agent.
+2. **File batching**: If a domain has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent.
 3. **Corresponding code/test files**: When batching by doc files, include only the matching code and test files for those specific docs (match by filename stem, e.g., `docs/commands/createFoo.md` → `command/createFoo.ts` + `command/createFoo.test.ts`).
 
 ### Agent Table
 
-| Check Type | Domain  | Prompt Template                                                                                            | Inputs per agent                                                     |
-| ---------- | ------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| M-1        | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                 | MODEL_DOCS (batch), MODEL_CODE (matching)                            |
-| C-1        | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md)                              | COMMAND_DOCS (batch), COMMAND_CODE (matching)                        |
-| C-2        | Command | [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md)      | COMMAND_DOCS (batch), COMMAND_CODE (matching), ERROR_DEFS            |
-| C-3        | Command | [references/command-doc-test-parity.md](references/command-doc-test-parity.md)                              | COMMAND_DOCS (batch), COMMAND_TEST_CODE (matching)                   |
-| Q-1        | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md)                                 | QUERY_DOCS (batch), QUERY_CODE (matching)                            |
-| Q-2        | Query   | [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md)          | QUERY_DOCS (batch), QUERY_CODE (matching), ERROR_DEFS               |
-| Q-3        | Query   | [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                                 | QUERY_DOCS (batch), QUERY_TEST_CODE (matching)                      |
+| Agent Type    | Domain  | Prompt Templates (all included in one agent)                                                                                                                                                                                                                                                     | Inputs per agent                                                                    |
+| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| M-1           | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                                                                                                                                                                                                       | MODEL_DOCS (batch), MODEL_CODE (matching)                                           |
+| C-1 + C-2 + C-3 | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md) + [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md) + [references/command-doc-test-parity.md](references/command-doc-test-parity.md) | COMMAND_DOCS (batch), COMMAND_CODE (matching), COMMAND_TEST_CODE (matching), ERROR_DEFS |
+| Q-1 + Q-2 + Q-3 | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md) + [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md) + [references/query-doc-test-parity.md](references/query-doc-test-parity.md)    | QUERY_DOCS (batch), QUERY_CODE (matching), QUERY_TEST_CODE (matching), ERROR_DEFS   |
 
 ### Batching Example
 
-If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 3 agents (C-1, C-2, C-3) → 9 command agents total. If it has 4 command docs: no batching needed, 3 agents (C-1, C-2, C-3).
+If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 1 agent (C-1+C-2+C-3) → 3 command agents total. If it has 4 command docs: no batching needed, 1 agent.
 
 For model docs: if 6 models → 2 batches (3+3) → 2 agents (M-1 × 2). If 3 models → 1 agent.
 
 ### Agent Dispatch
 
-For each agent:
+For combined agents (command or query), concatenate all prompt templates in order, then fill placeholders. For each agent:
 
-1. Read the prompt template file for that check type
-2. Replace `{{MODULE_NAME}}` with the resolved module name
-3. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
-4. Dispatch the agent with the filled prompt
+1. Read all prompt template files for that agent type
+2. Concatenate them in order with a `---` separator between each
+3. Replace `{{MODULE_NAME}}` with the resolved module name
+4. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
+5. Dispatch the agent with the filled prompt; instruct it to return a **single JSON result** with combined `gaps[]` and `inconsistencies[]` covering all check types
 
 **IMPORTANT**: Launch ALL agents across ALL domains in a single parallel message. Do not serialize by domain.
 

package/skills/erp-kit-module-shared/references/commands.md

@@ -180,9 +180,76 @@ const units = await db
 - **Error handling**: Use `ok()` / `err()` from `@tailor-platform/erp-kit/module` — do not throw
 - **Validation**: Check referenced entities exist before operating, return `err()` if not found
 
+## Update Command Input Type
+
+Update commands use a structured type that separates lookup keys from mutable fields, and explicitly excludes status-controlled fields.
+
+### Input type shape
+
+```typescript
+export type UpdateXInput = ({
+  id: string;
+} | {
+  naturalKey: string; // e.g. sku, code
+}) & {
+  mutableField1?: string;
+  mutableField2?: string | null;
+}
+```
+
+### Run signature with custom fields
+
+```typescript
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateXInput & Omit<Partial<CF>, "status">,
+  ctx: CommandContext,
+)
+```
+
+### Rules
+
+| Field kind | Examples | How to handle |
+|---|---|---|
+| Lookup key (primary) | `id` | One branch of the union |
+| Lookup key (natural) | `sku`, `code` | Another branch of the union — used to look up the record, not to update it |
+| Mutable fields | `name`, `barcode` | Listed in the `&` intersection as optional fields |
+| Status-controlled | `status` | **Never in the input type.** Managed by dedicated commands (`activateX`, `deactivateX`). Excluded from `CF` via `Omit`. |
+| System fields | `createdAt`, `updatedAt` | Never in the input type. Set automatically. |
+
+### Lookup implementation
+
+Use `"id" in input` to branch between lookup strategies:
+
+```typescript
+let query = db.selectFrom("Item").selectAll();
+if ("id" in input) {
+  query = query.where("id", "=", input.id);
+} else {
+  query = query.where("sku", "=", (input as { sku: string }).sku);
+}
+const item = await query.forUpdate().executeTakeFirst();
+```
+
+### Custom field extraction
+
+Destructure known fields and treat the rest as custom fields:
+
+```typescript
+const { name, barcode, unitId, ...rest } = input as any;
+const { id: _id, sku: _sku, ...customFields } = rest;
+```
+
+### Why not throw immutable errors
+
+Natural keys like `sku` or `code` are **lookup keys**, not updatable fields. They do not belong in the mutable section of the input type — the type system prevents callers from passing them as update targets. There is no need for a `SkuImmutableError` or `CodeImmutableError` in an update command.
+
+> Exception: conditionally-mutable fields (e.g., `baseCurrencyId` that can only change in DRAFT status) belong in the mutable section and use a business-rule error when the condition is not met.
+
 ## Conventions
 
-- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Input types for create commands: exported interfaces (`export interface CreateXInput`)
+- Input types for update commands: exported type aliases (`export type UpdateXInput = ...`)
 - Use `.executeTakeFirst()` for single results
 - Include JSDoc: `/** Function: name \n Description */`