freepasserp4

FreePass ERP v4 targets sub-prime, no-credit-check car-rental brokerage. It replaces v3's custom router and page fragmentation with the five-layer atomic architecture proven in jpkerp6, adapted to the FreePass domain. v3 remains live on Vercel; v4 is built locally first, then migrated after stabilization. Run with npm install and npm run dev on http://localhost:4004. If Firebase is not configured, lib/store.ts falls back to a LocalAdapter using localStorage, and lib/seed.ts injects sample contracts on first run. The architecture has five layers: 1) Entity SSOT (lib/intake/entities.ts) defines ENTITIES that generate direct-input, Excel, and OCR forms simultaneously, including ocrFrom, manual, idFrom. 2) Storage atom (lib/store.ts) provides a single StoreAdapter (Local, Firestore, Dispatch) handling natural-key deduplication, soft-delete, and company isolation via companyId. 3) UI atoms (components/ui/index.tsx) supply ObjCard (56px list atom), Sec, Cards, Metric, Badge, DataTable (mobile renders as cards), Modal, FormGrid. 4) Sections (cockpit in app/page.tsx) classify state-driven questions into pending-review, pending-dispatch, in-operation, recovery, and receivables. 5) Domain engines (lib/domain/*) are pure functions calculating marginFee (supplier fee minus sales fee) and clawbackWatch (no-guarantor 3- and 6-month recovery). Unlike jpkerp (direct-operation), vehicles center on supplier, supply price, and margin; contracts focus on product type, review, salesperson, commission, and recovery. Partner (salesperson) and supplier are two-sided entities absent in direct-operation. Design rules: compose only with atoms and cards (reuse ObjCard+Sec for new lists/details, no hand-rolled cards/inline), unify web and mobile (atoms use useIsMobile for responsive behavior, dedicated views only with explicit agreement), prevent structural errors (no named exports in route files, separate dev/build, avoid string date comparison, show remainder on silent truncation). Completed: skeleton, infrastructure, entity SSOT, home cockpit (contract slice). Pending: contract detail drawer, review/dispatch/sign actions, commission settlement, recovery tracking, vehicle (inventory), salesperson, supplier slices, OCR intake (contract, license, registration), Excel import, v3-to-v4 migration adapter, FreePass-specific Firebase remote connection. All AI contributors must read AGENTS.md for role division (Claude=design/gate, Cursor=implementation, Codex=full verification) and immutable rules/gates before starting work.