@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @tailor-platform/erp-kit
 
+## 0.9.0
+
+### Minor Changes
+
+- afa2455: - Add seed:validate script and skill step to scaffold template
+  - Add vitest to module scaffold template
+  - Add version self-checking to all erp-kit skills
+  - Fix command return properties to use full model names across all modules
+  - Fix tree-shaking by adding sideEffects annotations to all module defineModule exports
+  - Fix scaffold app integration tests
+  - Fix inactive users being able to access the scaffold app
+  - Fix skills CLI version check, remove erp-kit-shared dependency
+  - Refactor audit pages out of user-management directory into standalone location
+  - Remove audit dependency from coa-management module
+
+## 0.8.0
+
+### Minor Changes
+
+- 16f35c6: - Add project scaffolding to `erp-kit init` command (pnpm workspace, package.json, directory structure)
+  - Add accounting module implementation with models, commands, queries, and test fixtures
+  - Add app-shell primitives and component cheat sheet reference for frontend implementation skill
+  - Improve frontend templates by consolidating duplicate UI components into shared packages
+  - Update manufacturing module documentation with additional model and command details
+- cdb3690: - Add user-management scaffold template with full RBAC and audit support
+  - Add `update` command pattern with union lookup keys for flexible record updates
+  - Add app-shell primitives and detail-view reference for frontend implementation
+  - Fix app scaffold expansion to exclude docs directory from template processing
+  - Improve update command conventions with followup refinements
+- 16f35c6: - Add manufacturing module with BOM, work orders, and production tracking
+  - Add story test case sync-check and stub generation for `erp-kit test` command
+  - Update workspace creation instructions and deployment steps in skills
+
+### Patch Changes
+
+- 16f35c6: - Fix relative shared imports to use package self-reference for consistent module resolution
+  - Fix priority calibration in requirements review skill to improve accuracy
+  - Fix severity validation in module-2 requirements review skill
+  - Update module-4-plan-review skill and regenerate .agents/skills
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -11,8 +11,8 @@ npm install @tailor-platform/erp-kit
 ## Quick Start
 
 ```bash
-# Set up your repo (agent skills, workflows, configs)
-erp-kit init
+# Set up your repo (agent skills, workflows, project structure)
+erp-kit init my-project
 
 # Update framework resources
 erp-kit update
@@ -57,15 +57,19 @@ erp-kit mock validate
 First-time setup for consumer repos. Fails if already initialized — use `erp-kit update` to refresh resources.
 
 ```bash
-erp-kit init
+erp-kit init <name>
 ```
 
+**Arguments:**
+
+- `<name>` — Project name (used in `package.json`)
+
 This will:
 
 1. Copy agent skills to `.agents/skills/`
 2. Create symlink `.claude/skills` → `.agents/skills/`
 3. Copy workflows to `.github/workflows/`
-4. Copy config files
+4. Scaffold project structure (`package.json`, `pnpm-workspace.yaml`, `.gitignore`, `license.config.json`, `apps/`, `modules/`)
 
 ### `update`
 

package/dist/cli.mjs

@@ -31,10 +31,70 @@ function readErpKitVersion() {
 	return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf-8")).version;
 }
 //#endregion
+//#region src/generator/scaffold.ts
+const RENAME_MAP = {
+	__dot__gitignore: ".gitignore",
+	"__pnpm-workspace.yaml": "pnpm-workspace.yaml"
+};
+function copyTemplateDir(srcDir, destDir, replacements, placeholderFiles, excludeDirs = /* @__PURE__ */ new Set()) {
+	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+		const srcPath = path.join(srcDir, entry.name);
+		const destName = RENAME_MAP[entry.name] ?? entry.name;
+		const destPath = path.join(destDir, destName);
+		if (entry.name === "node_modules") continue;
+		if (excludeDirs.has(entry.name)) continue;
+		if (entry.isDirectory()) {
+			fs.mkdirSync(destPath, { recursive: true });
+			copyTemplateDir(srcPath, destPath, replacements, placeholderFiles, excludeDirs);
+		} else {
+			if (fs.existsSync(destPath)) continue;
+			fs.mkdirSync(path.dirname(destPath), { recursive: true });
+			if (placeholderFiles.has(entry.name)) {
+				let content = fs.readFileSync(srcPath, "utf-8");
+				for (const [from, to] of Object.entries(replacements)) content = content.replaceAll(from, to);
+				fs.writeFileSync(destPath, content);
+			} else fs.copyFileSync(srcPath, destPath);
+		}
+	}
+}
+function scaffoldModuleBoilerplate(moduleDir, moduleName) {
+	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "module");
+	const erpKitVersion = readErpKitVersion();
+	copyTemplateDir(templateDir, moduleDir, {
+		"template-module": moduleName,
+		"\"workspace:*\"": `"${erpKitVersion}"`
+	}, new Set([
+		"package.json",
+		"permissions.ts",
+		"tailor.config.ts"
+	]));
+}
+function scaffoldAppBoilerplate(appDir, appName) {
+	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
+	const erpKitVersion = readErpKitVersion();
+	copyTemplateDir(templateDir, appDir, {
+		"template-app-frontend": `${appName}-frontend`,
+		"template-app-backend": appName,
+		"template-app": appName,
+		"\"workspace:*\"": `"${erpKitVersion}"`
+	}, new Set([
+		"package.json",
+		"tailor.config.ts",
+		"index.html"
+	]), new Set(["docs"]));
+}
+function scaffoldProjectBoilerplate(projectDir, projectName) {
+	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "project");
+	const erpKitVersion = readErpKitVersion();
+	copyTemplateDir(templateDir, projectDir, {
+		"template-project": projectName,
+		"\"workspace:*\"": `"${erpKitVersion}"`
+	}, new Set(["package.json"]));
+}
+//#endregion
 //#region src/commands/lib/distribute.ts
 const SKILLS_SRC = path.join(PACKAGE_ROOT, "skills");
 const WORKFLOWS_SRC = path.join(PACKAGE_ROOT, "templates", "workflows");
-const CONFIG_SRC = path.join(PACKAGE_ROOT, "templates", "config");
 function copyDirectoryRecursive(srcDir, destDir) {
 	let copied = 0;
 	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
@@ -95,22 +155,6 @@ function copyWorkflows(cwd) {
 		removed: 0
 	};
 }
-function copyConfigs(cwd) {
-	if (!fs.existsSync(CONFIG_SRC)) return {
-		copied: 0,
-		removed: 0
-	};
-	let copied = 0;
-	for (const entry of fs.readdirSync(CONFIG_SRC)) {
-		const destPath = path.join(cwd, entry);
-		fs.copyFileSync(path.join(CONFIG_SRC, entry), destPath);
-		copied++;
-	}
-	return {
-		copied,
-		removed: 0
-	};
-}
 function createSymlink(target, linkPath) {
 	const type = process.platform === "win32" ? "junction" : void 0;
 	const resolvedTarget = type === "junction" ? path.resolve(path.dirname(linkPath), target) : target;
@@ -179,7 +223,7 @@ function isAlreadyInitialized(cwd) {
 }
 //#endregion
 //#region src/commands/init.ts
-function runInit(cwd) {
+function runInit(name, cwd) {
 	console.log(chalk.bold("erp-kit init\n"));
 	if (isAlreadyInitialized(cwd)) {
 		console.log(chalk.yellow("Already initialized. Use `erp-kit update` to refresh framework resources."));
@@ -193,8 +237,8 @@ function runInit(cwd) {
 	else if (symlink === "skipped_directory") console.log(chalk.yellow("  Skipped .claude/skills (directory exists, not a symlink)"));
 	const workflows = copyWorkflows(cwd);
 	if (workflows.copied > 0) console.log(chalk.green(`  Copied ${workflows.copied} workflow(s) to .github/workflows/`));
-	const configs = copyConfigs(cwd);
-	if (configs.copied > 0) console.log(chalk.green(`  Copied ${configs.copied} config file(s)`));
+	scaffoldProjectBoilerplate(cwd, name);
+	console.log(chalk.green("  Scaffolded project structure"));
 	console.log(chalk.bold.green("\nDone! Run `erp-kit check` to validate your docs."));
 	return 0;
 }
@@ -1176,54 +1220,6 @@ function renderStub(type, name, testCases) {
 	return templates[type].render(name);
 }
 //#endregion
-//#region src/generator/scaffold.ts
-function copyTemplateDir(srcDir, destDir, replacements, placeholderFiles) {
-	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-		const srcPath = path.join(srcDir, entry.name);
-		const destName = entry.name === "__dot__gitignore" ? ".gitignore" : entry.name;
-		const destPath = path.join(destDir, destName);
-		if (entry.name === "node_modules") continue;
-		if (entry.isDirectory()) {
-			fs.mkdirSync(destPath, { recursive: true });
-			copyTemplateDir(srcPath, destPath, replacements, placeholderFiles);
-		} else {
-			if (fs.existsSync(destPath)) continue;
-			fs.mkdirSync(path.dirname(destPath), { recursive: true });
-			if (placeholderFiles.has(entry.name)) {
-				let content = fs.readFileSync(srcPath, "utf-8");
-				for (const [from, to] of Object.entries(replacements)) content = content.replaceAll(from, to);
-				fs.writeFileSync(destPath, content);
-			} else fs.copyFileSync(srcPath, destPath);
-		}
-	}
-}
-function scaffoldModuleBoilerplate(moduleDir, moduleName) {
-	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "module");
-	const erpKitVersion = readErpKitVersion();
-	copyTemplateDir(templateDir, moduleDir, {
-		"template-module": moduleName,
-		"\"workspace:*\"": `"${erpKitVersion}"`
-	}, new Set([
-		"package.json",
-		"permissions.ts",
-		"tailor.config.ts"
-	]));
-}
-function scaffoldAppBoilerplate(appDir, appName) {
-	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
-	const erpKitVersion = readErpKitVersion();
-	copyTemplateDir(templateDir, appDir, {
-		"template-app-frontend": `${appName}-frontend`,
-		"template-app-backend": appName,
-		"template-app": appName,
-		"\"workspace:*\"": `"${erpKitVersion}"`
-	}, new Set([
-		"package.json",
-		"tailor.config.ts",
-		"index.html"
-	]));
-}
-//#endregion
 //#region src/generator/generate-code.ts
 function runGenerateCode(modulePath, moduleName) {
 	scaffoldModuleBoilerplate(modulePath, moduleName);
@@ -3085,9 +3081,13 @@ runMain(defineCommand({
 		init: defineCommand({
 			name: "init",
 			description: "First-time setup for a consumer repo",
-			run: () => {
+			args: z.object({ name: arg(z.string(), {
+				positional: true,
+				description: "Project name"
+			}) }),
+			run: (args) => {
 				return executeCommand(() => {
-					const exitCode = runInit(cwd);
+					const exitCode = runInit(args.name, cwd);
 					return exitCode === 0 ? success() : silentFailure(exitCode);
 				});
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-1-requirements
 description: Create Tier 1-2 documentation (requirements, actors, business-flow) for an application. Use when starting a new application or documenting high-level requirements and workflows.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Application Requirement Analysis Workflow
 
 Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## 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.

package/skills/erp-kit-app-2-requirements-review/SKILL.md

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-2-requirements-review
 description: Review requirements quality and documentation consistency for applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Requirements Review
 
 Review **requirements quality** and **documentation consistency** for an application's Tier 1-2 documentation.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## 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.

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-3-plan
 description: Create Tier 3-4 documentation (screens, resolvers) by breaking down business flows and existing stories. Use after completing requirements review with erp-kit-app-2-requirements-review.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Business Flow Breakdown to Stories, Screens, and Resolvers
 
 Convert Tier 2 business flows and stories into Tier 3 (screens) and Tier 4 (resolvers) documentation using parallel extraction agents.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## 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.

package/skills/erp-kit-app-4-plan-review/SKILL.md

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-4-plan-review
 description: Review parity between Tier 2 (business flows, actors, stories) and Tier 3-4 (screens, resolvers). Use after creating plan documentation with erp-kit-app-3-plan to validate completeness.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Documentation Parity Review
 
 Review **documentation consistency** across Tier 2 (business flows, actors, stories), Tier 3 (screens), and Tier 4 (resolvers) documentation.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## 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.

package/skills/erp-kit-app-5-impl-backend/SKILL.md

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-5-impl-backend
 description: Implement backend code for applications using erp-kit modules. Use after completing plan review with erp-kit-app-4-plan-review. Triggers when implementing backend resolvers, wiring modules, configuring applications, or when the user mentions implementing backend, writing resolvers, or connecting erp-kit modules.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Application Backend Implementation
 
 Implement backend resolvers and application configuration for an application, driven by Tier 1-4 documentation (actors, business flows, stories, screens, resolvers).
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## 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.
@@ -67,17 +73,17 @@ Classify resolvers per [erp-kit-app-shared/references/resolver-classification.md
 
 When implementing in Phase 4, follow the patterns from the reference examples. Once all actual resolvers are implemented, delete the reference files that aren't needed by your app.
 
-### Phase 2: Wire Modules (`src/modules.ts`)
+### Phase 2: Wire Modules (`src/modules.ts` + `src/modules-db.ts`)
 
-Create the module wiring file that composes all required erp-kit modules.
+Create the module wiring files that compose all required erp-kit modules.
 
 **Read [module wiring reference](references/module-wiring.md) for the composition pattern.**
 
 Key points:
 
-- Use `defineXxxModule()` functions from `@tailor-platform/erp-kit/module`
+- `modules.ts` — Use `defineXxxModule()` functions from `@tailor-platform/erp-kit/module` and export module objects for resolver use
+- `modules-db.ts` — Destructure DB types into individual named exports for the DB scanner. This file must NOT be imported by resolvers.
 - Pass inter-module dependencies explicitly (e.g., item-management needs primitives' unit type and query)
-- Export `db`, `commands`, and `executors` for use in resolvers
 
 ### Phase 3: Configure Application (`tailor.config.ts`)
 
@@ -109,7 +115,7 @@ After resolvers are done, implement the story integration test stubs generated i
 > - `src/resolvers/<resolverName>.ts`
 > - `src/executors/<resolverName>.ts`
 >
-> **Shared-file guard:** `src/modules.ts` and `tailor.config.ts` are written in the sync barrier phase above. Resolver agents must NOT modify these files.
+> **Shared-file guard:** `src/modules.ts`, `src/modules-db.ts`, and `tailor.config.ts` are written in the sync barrier phase above. Resolver agents must NOT modify these files.
 
 ### Phase 5: Generated Files
 
@@ -117,6 +123,7 @@ After resolvers are done, implement the story integration test stubs generated i
 - **Seed data** (`seed/`) — `exec.mjs` runner + `data/*.jsonl` (records) and `data/*.schema.ts` (validation).
   1. **Module seed** — Run `pnpm erp-kit app generate seed -p <app-path>` to generate module-provided defaults (currencies, units, UoM categories, exchange rates). This writes JSONL files to `seed/data/`, skipping files that already exist.
   2. **App-specific seed** — Manually create seed records for permissions, roles, test users, and domain-specific data. Seeded users must have concrete permission keys required by the wired modules.
+  3. **Validate seed** — Run `pnpm run seed:validate` and fix any errors before proceeding.
 
 ### Phase 6: Deploy Backend & Next Steps
 

package/skills/erp-kit-app-5-impl-backend/references/app-config.md

@@ -11,7 +11,7 @@ Key points:
 ## Auth configuration
 
 - Prefer stable default naming: auth `default`, IdP `default`, OAuth2 client `default`
-- `userProfile.type` must reference the `user` DB type from `modules.ts`
+- `userProfile.type` must reference the `user` DB type from `modules-db`
 - `userProfile.usernameField`: stable unique field (e.g., `email`)
 - Include static website URL and localhost in CORS: `cors: ["http://localhost:5173", website.url]`
 - Frontend `VITE_TAILOR_CLIENT_ID` must come from `tailor-sdk oauth2client get default --json` — do not hardcode

package/skills/erp-kit-app-5-impl-backend/references/module-wiring.md

@@ -1,17 +1,23 @@
 # Module Wiring
 
-`src/modules.ts` composes erp-kit modules and exports their parts for resolver use.
+Module wiring is split across two files:
+
+- `src/modules.ts` — composes erp-kit modules and exports module objects for resolver use
+- `src/modules-db.ts` — destructures DB types into individual named exports for the DB scanner (`tailor.config.ts` db.files)
+
+### `src/modules.ts`
 
 ```ts
 import {
   definePrimitivesModule,
   defineUserManagementModule,
   defineItemManagementModule,
+  defineAuditModule,
 } from "@tailor-platform/erp-kit/module";
 
 const primitivesModules = definePrimitivesModule({});
 
-const umModules = defineUserManagementModule({
+export const umModules = defineUserManagementModule({
   dbNamespace: "main-db",
   user: {
     fields: {
@@ -22,26 +28,45 @@ const umModules = defineUserManagementModule({
 });
 
 // Pass inter-module dependencies explicitly
-const imModules = defineItemManagementModule({
+export const imModules = defineItemManagementModule({
   primitives: {
     db: { unit: primitivesModules.db.unit },
     queries: { getUnit: primitivesModules.queries.getUnit },
   },
 });
 
-// Destructure db into individual table exports (required for DB scanner)
-export const { db: primitivesDb, commands: primitivesCommands } = primitivesModules;
-export const { uomCategory, unit, currency, exchangeRate } = primitivesDb;
+export const auditModules = defineAuditModule();
+
+export const primitivesModulesExport = primitivesModules;
+```
+
+### `src/modules-db.ts`
+
+```ts
+import { auditCompanyStub } from "@tailor-platform/erp-kit/module";
+import { umModules, imModules, primitivesModulesExport, auditModules } from "./modules";
+
+// Destructured for DB scanner (tailor.config.ts db.files).
+// This file must NOT be imported by resolvers — property access prevents tree-shaking.
+
+// user-management
+export const { user, permission, role, userRole, rolePermission } = umModules.db;
+
+// primitives
+export const { uomCategory, unit, currency, exchangeRate } = primitivesModulesExport.db;
 
-export const { db: umDb, executors: umExecutors, commands: umCommands } = umModules;
-export const { user, permission, role, userRole, rolePermission, auditEvent } = umDb;
+// item-management
+export const { item, taxonomyNode, itemTaxonomyAssignment } = imModules.db;
 
-export const { db: imDb, commands: imCommands } = imModules;
-export const { item, taxonomyNode, itemTaxonomyAssignment } = imDb;
+// audit
+export const { auditableEntity, auditPolicy, policyFieldRule, auditEntry, changeDetail } =
+  auditModules.db;
+export { auditCompanyStub as company };
 ```
 
 Key conventions:
 
-- Prefix exports to avoid collisions (`umCommands`, `imCommands`, `primitivesCommands`)
-- Every module's `db` must be destructured into individual table exports — the DB scanner only picks up named exports
+- Prefix exports to avoid collisions (`umModules`, `imModules`, `auditModules`)
+- `modules-db.ts` must NOT be imported by resolvers — it exists solely for the DB scanner
+- Every module's `db` must be destructured into individual table exports in `modules-db.ts` — the DB scanner only picks up named exports
 - Extract individual executors for re-export in executor files

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

@@ -1,12 +1,18 @@
 ---
 name: erp-kit-app-6-impl-frontend
 description: Implement frontend code for applications. Use after deploying the backend with erp-kit-app-5-impl-backend. Triggers when implementing frontend pages, creating React components from screen specs, or when the user mentions implementing frontend, creating pages, or building UI for an application.
+metadata:
+  erp-kit-version: "0.9.0"
 ---
 
 # Application Frontend Implementation
 
 Implement frontend pages for an application, driven by screen spec documentation and a deployed backend.
 
+## Version Check
+
+Run `npx erp-kit --version` and compare against this skill's `metadata.erp-kit-version`. If they differ, the local skills are outdated — tell the user to run `pnpm erp-kit update skills` and stop.
+
 ## 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.
@@ -76,6 +82,8 @@ Create pages driven by screen spec docs. Each screen type has a standard impleme
 
 **Read [pages reference](references/pages.md) for the full pattern catalog.**
 
+**Read [app-shell UI cheat sheet](references/component.md)** for `@tailor-platform/app-shell` primitives (Layout, Button, Table, dialogs, Menu, Select, Combobox, Autocomplete, etc.).
+
 Page types and their file structure:
 
 | Screen Type   | Files                                                                                            |
@@ -91,7 +99,7 @@ Key frontend patterns:
 - **gql.tada** — Type-safe GraphQL via `graphql()` from `@/graphql`
 - **React Hook Form + Zod** — Form validation with `zodResolver`
 - **urql** — `useQuery` for reads, `useMutation` for writes
-- **app-shell routing** — `Layout`, `Link`, `useParams`, `useNavigate` from `@tailor-platform/app-shell`
+- **app-shell** — Routing: `Layout`, `Link`, `useParams`, `useNavigate`. UI: see [references/component.md](references/component.md) for primitives (`Button`, `Input`, `Table`, dialogs, menus, selects, etc.)
 
 ### Phase 4: Verify
 

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

@@ -0,0 +1,90 @@
+# @tailor-platform/app-shell — UI cheat sheet
+
+Import from `@tailor-platform/app-shell` instead of duplicating shadcn-style `components/ui` when possible. Details: [app-shell docs/components](https://raw.github.com/tailor-platform/app-shell/tree/main/docs/components).
+
+## Layout
+
+- **`Layout`** — `title` / `actions` / `columns` still work; prefer **`Layout.Header`** (`title`, `actions`, children e.g. tabs) + **`Layout.Column`**.
+- **`Layout.Column` `area`** — `"left" | "main" | "right"` for sidebar + main + rail; use `className` on `Layout` for gap (`columns` / `gap` deprecated).
+
+## ActionPanel
+
+`actions={[{ key, label, icon, onClick, disabled?, loading? }]}` — icon + label rows; use `useNavigate` inside `onClick` for routing.
+
+## Routing helpers
+
+`Link`, `useNavigate`, `useParams` — same package.
+
+## DescriptionCard
+
+Detail screens: **`data`** + **`fields`** render a responsive key/value grid.
+
+| Prop                  | Notes                                                                  |
+| --------------------- | ---------------------------------------------------------------------- |
+| `data`                | `Record<string, unknown>` — values (dot keys OK, e.g. `customer.name`) |
+| `fields`              | `FieldConfig[]` — each field or `{ type: "divider" }`                  |
+| `columns`             | `2` \| `3` (default) \| `4`                                            |
+| `className` / `style` | Card container                                                         |
+
+**Field config** — `key`, `label`, optional `type`, `meta`, `emptyBehavior` (`"dash"` \| `"hide"`).
+
+| `type` (default `text`) | Role / typical `meta`                                         |
+| ----------------------- | ------------------------------------------------------------- |
+| **text**                | `copyable`, `truncateLines`                                   |
+| **badge**               | `badgeVariantMap: { [value]: variant }`                       |
+| **money**               | `currencyKey` — key in `data` for ISO currency code           |
+| **date**                | `dateFormat`: `short` \| `medium` \| `long` \| `relative`     |
+| **link**                | `hrefKey`, `external?`                                        |
+| **address**             | Value = `{ street, city, state, zip, … }` object              |
+| **reference**           | `referenceIdKey`, `referenceUrlPattern` e.g. `/invoices/{id}` |
+
+## Button / Link
+
+Use **`render`**, not Radix `asChild`:
+
+```tsx
+<Button render={<Link to="create" />}>Create</Button>
+```
+
+Variants: `default` | `destructive` | `outline` | `secondary` | `ghost` | `link`. Sizes: `default` | `sm` | `lg` | `icon`.
+
+## Input
+
+Native input props; works with RHF `FormControl` + spread `field`.
+
+## Table
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head />
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell />
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+Also `Footer`, `Caption`. Wrapper: `containerClassName`; inner table: `className`.
+
+## Dialog / Sheet / Tooltip
+
+Compound `*.Root`, `*.Content`, etc. Triggers: **`render={<Button />}`** (or `Link` pattern as needed).
+
+## Menu
+
+`Menu.Root` → `Trigger` → `Content` → `Item` / `Separator` / checkbox & radio items; nested: `SubmenuRoot` / `SubmenuTrigger`.
+
+## Select / Combobox / Autocomplete
+
+| Component        | Use case                                  | Extras                           |
+| ---------------- | ----------------------------------------- | -------------------------------- |
+| **Select**       | `items`, `placeholder`, `onValueChange`   | `Select.Async`                   |
+| **Combobox**     | Searchable; `items`; multi / creatable    | `Combobox.Async`, `onCreateItem` |
+| **Autocomplete** | Typed string + suggestions (value = text) | `Autocomplete.Async`             |
+
+**`.Parts`** on each — low-level `Root`, `Trigger`, `Content`, …; hooks `useFilter`, `useAsync`, `useCreatable` for custom UIs.