build: enforce and document @yieldvault/api-schemas build order

CONTRIBUTING.md

@@ -29,10 +29,15 @@ git clone https://github.com/yourusername/YieldVault-RWA.git
 cd YieldVault-RWA
 
 # Install dependencies
-npm ci               # Backend
-cd frontend && npm ci # Frontend
+pnpm install
+
+# Build shared packages (required before backend type-checking or building)
+npm run build:schemas   # Or: cd packages/api-schemas && npm run build
 ```
 
+> **Important (Build Order):** The `@yieldvault/api-schemas` package must be built prior to running TypeScript (`tsc`), local type-checking, or building the backend. Running `npm run build` or `npm run dev` in the backend will automatically execute `build:schemas` via `prebuild`/`predev` hooks, but manual `tsc --noEmit` invocations require `dist` in `packages/api-schemas` to be generated first.
+
+
 ### Environment Configuration
 
 Copy environment templates and configure for local development:

backend/docs/REQUEST_VALIDATION.md

@@ -36,6 +36,9 @@ webhook register/update reject unknown keys).
 | `backend/src/middleware/validate.ts` | Auth, alias, webhook register schemas + middleware |
 | `packages/api-schemas` | Shared vault deposit/withdrawal contracts |
 
+> **Build Order:** The `@yieldvault/api-schemas` package must be built (`npm run build:schemas` or `npm run build` in backend) before TypeScript typechecking (`tsc --noEmit`) can resolve types imported by `backend/src/middleware/validate.ts`.
+
+
 ## Common rules
 
 - **Stellar addresses** on login/nonce: checksummed `G…` public keys.

backend/package.json

@@ -4,11 +4,14 @@
   "description": "YieldVault Stellar RWA Backend API",
   "main": "dist/index.js",
   "scripts": {
+    "predev": "npm run build:schemas",
     "dev": "tsx watch src/index.ts",
+    "build:schemas": "npm --prefix ../packages/api-schemas run build",
+    "prebuild": "npm run build:schemas && npm run prisma:generate",
     "prebuild": "npm run prisma:generate",
     "build": "npm run prisma:generate && tsc",
     "build": "tsc",
-    "pretypecheck": "npm run prisma:generate",
+    "pretypecheck": "npm run build:schemas && npm run prisma:generate",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "test": "jest --runInBand --coverage",

docs/CONTRIBUTOR_ONBOARDING_CHECKLIST.md

@@ -153,8 +153,13 @@ cd YieldVault-RWA
 
 # Install root-level dependencies (Husky git hooks, etc.)
 npm install
+
+# Build shared packages (build order requirement before backend typecheck or dev)
+npm run build:schemas
 ```
 
+> **Build Order Requirement:** `@yieldvault/api-schemas` must be built before local typechecking or starting the backend. Without this step, `tsc --noEmit` fails because `backend/src/middleware/validate.ts` imports `@yieldvault/api-schemas`.
+
 ### Verify Git Hooks
 
 ```bash
@@ -171,7 +176,7 @@ ls .husky/pre-commit
 ```bash
 cd backend
 
-# Install dependencies
+# Install dependencies (prebuild/predev will build api-schemas automatically)
 npm install
 
 # Create environment file from template

docs/LOCAL_DEV_BOOTSTRAP.md

@@ -56,13 +56,21 @@ git config core.hooksPath .husky
 Install dependencies for each application separately:
 
 ```bash
+# Build shared API schemas first (required before backend typecheck or build)
+cd packages/api-schemas
+npm install
+npm run build
+cd ..
+
 cd backend
 npm install
 cd ../frontend
 npm install
 cd ..
 ```
 
+> **Note on Build Order:** `@yieldvault/api-schemas` is a workspace package imported by backend middleware (`backend/src/middleware/validate.ts`). Without building `packages/api-schemas` first, TypeScript compilation (`tsc --noEmit`) fails with `Cannot find module '@yieldvault/api-schemas'`. Always ensure `packages/api-schemas` is built first (or use root `npm run build:schemas`).
+
 If a workspace uses a lockfile, prefer the package manager and frozen-lockfile command specified by that lockfile and by CI.
 
 ## 2. Configure the backend

package.json

@@ -23,9 +23,12 @@
     "test": "vitest run",
     "lint:staged": "lint-staged",
     "commitlint": "commitlint",
+    "build:schemas": "npm --prefix packages/api-schemas run build",
+    "build": "pnpm build:schemas && pnpm --filter backend build && pnpm --filter frontend build",
+    "typecheck": "pnpm build:schemas && pnpm --filter backend typecheck && pnpm --filter frontend build",
     "dev": "concurrently \"pnpm:dev:backend\" \"pnpm:dev:frontend\"",
-    "dev:backend": "bash scripts/wait-for-db.sh && pnpm --filter backend dev",
-    "dev:frontend": "pnpm --filter frontend dev",
+    "dev:backend": "pnpm build:schemas && bash scripts/wait-for-db.sh && pnpm --filter backend dev",
+    "dev:frontend": "pnpm build:schemas && pnpm --filter frontend dev",
     "wait-for-db": "bash scripts/wait-for-db.sh",
     "test": "pnpm --filter backend test -- --runInBand --coverage && pnpm --filter frontend test --run",
     "test:backend": "pnpm --filter backend test -- --runInBand --coverage",