Software Updates

dashboard periodStart/periodEnd + reports API request body alignment

• payroll-dashboard-client: payPeriod.startDate → payPeriod.periodStart/periodEnd
• reports-client: fix request body to send reportType (not type), wrap filters in filters object, handle flat API response { reportType, data, format } instead of nested data.report

align all UI client pages with API response shapes

• people-directory-client: fix interface to match flat API response (workerStatus, entityName, managerName, firstName/lastName vs nested objects)
• worker-profile-client: profile.entity → profile.legalEntity, profile.currentCompensation → profile.compensationPlans[0], profile.onboardingStatus → profile.onboardingWorkflows[0]
• payroll-runs-client: payPeriod.startDate → payPeriod.periodStart/periodEnd
• payroll-run-detail-client: same periodStart/periodEnd fix
• new-payroll-run-client: data.periods → data.data
• new-worker-client: fix POST body field names (entityId→legalEntityId, displayName→firstName/lastName, hireDate→startDate), fix response (data.worker.id→data.id)
• invoices-client: fix Invoice interface to match API (workerName flat string, nullable dueDate, entity nullable), add dueDate to API response
• payroll-settings-client: fix all response keys (d.entities→d.data, etc.), fix field names (legalName→name, defaultCurrency→currency, etc.)

add migration 017 for schema fixes (runNumber, PayrollAdjustment FK, TimeEntry approval)

align all 22 API routes with Prisma schema + RBAC permissions

• Fixed field name mismatches across all route files: entity→legalEntity, entityId→legalEntityId, startDate→periodStart, endDate→periodEnd, clockIn→clockInAt, clockOut→clockOutAt, etc.
• Fixed all permission references to match RBAC PERMISSIONS object: SETTINGS_MANAGE→ENTITIES_EDIT/ROLES_EDIT/SETTINGS_EDIT/GL_MAPPING_EDIT/INTEGRATIONS_EDIT PAYROLL_RUN→PAYROLL_PROCESS, GL_VIEW→GL_EXPORT, INVOICES_CREATE→INVOICES_APPROVE, PAYMENTS_MANAGE→PAYMENTS_CREATE, LEAVE_VIEW→LEAVE_VIEW_ALL, LEAVE_REQUEST_OWN→LEAVE_SUBMIT_OWN, LEAVE_MANAGE→LEAVE_APPROVE, ONBOARDING_VIEW_OWN→ONBOARDING_VIEW
• Fixed status enum values to use prefixed versions: DRAFT→AGREEMENT_DRAFT, INITIATED→OFF_INITIATED, PENDING→OB_TASK_PENDING/OFF_TASK_PENDING, COMPLETED→OB_TASK_COMPLETED, INACTIVE→INT_DISCONNECTED, FULL_DAY→FEDERAL
• Added missing schema fields: PayrollRun.runNumber, TimeEntry approval fields, PayrollAdjustment.workerProfile relation
• Extended audit.ts with HRIS entity types, action types, and categories
• Removed non-existent field references (slug, encryptedCredentials, etc.)
• All 22 route files verified: ZERO TypeScript compile errors
• Added KATURA_BUSINESS_INTELLIGENCE_PLATFORM.md

HRIS/Payroll UI pages + navigation + i18n

• /admin/payroll — Payroll Dashboard (stats, quick actions, recent runs)
• /admin/payroll/runs — Payroll Runs list with status filters
• /admin/payroll/runs/[id] — Run detail with calculate/approve/reject/void
• /admin/payroll/runs/new — New payroll run creation form
• /admin/payroll/invoices — Contractor invoices list with overdue tracking
• /admin/payroll/reports — Reports generator (5 types: payroll summary, headcount, compensation analysis, leave summary, contractor payments)
• /admin/payroll/periods — Pay periods management with bulk generation
• /admin/people/[id] — Worker Profile with 7-tab layout (overview, compensation, time, leave, documents, agreements, onboarding)
• /admin/people/new — New worker creation form (US/Brazil, W-2/1099/CLT/PJ)
• /admin/settings/payroll — Settings hub (entities, roles, tax tables, holidays, integrations)
• Added People & HR group (People Directory + Team)
• Added Payroll group (Dashboard, Runs, Invoices, Reports)
• Renamed Content & Team to Content (Team moved to People & HR)
• Added quick actions: Add Worker, New Payroll Run
• Desktop sidebar now renders grouped navigation with labels
• Added EN/PT translations for all new nav items and groups
• peopleDirectory, payrollDashboard, payrollRuns, invoices, payrollReports
• groupPeopleAndHR, groupPayroll, groupContent, addWorker, newPayrollRun

scoring normalization + seed real data for all 50 cities

• Fix scoring route to use min-max normalization (0-100 scale) instead of raw value * weight
• Invert negative weights (cost/friction metrics) so lower = better score
• Seed real-world data for 38 international cities (seed-market-data.cjs)
• Seed remaining 12 US cities (seed-remaining-us.cjs): Austin, Boston, Greenwich, Las Vegas, Naples, Newport Beach, Raleigh-Durham, San Diego, Seattle, Short Hills, Tysons, Washington
• All 50 cities now have 10 metric dimensions with confidence scores
• Add check-data.cjs utility to verify data coverage
• Add payroll module: 16 SQL migrations, API routes, tax engine, RBAC
• Add people directory pages

Use Prisma.JsonNull for nullable Json fields in audit.ts

• Prisma requires Prisma.JsonNull (not plain null) for nullable Json columns.

Order field is 'total' not 'totalAmount' in summary route

Remove invalid COMPLETED OrderStatus from summary route

• OrderStatus enum: PENDING, PAID, IN_PRODUCTION, SHIPPED, DELIVERED, CANCELLED, REFUNDED
• Was using non-existent 'COMPLETED' — replaced with valid statuses.

Restore 0-byte route files causing Vercel build failure

• api/admin/business-planning/budgets/route.ts (91 lines) — GET/POST budget CRUD
• api/admin/business-planning/summary/route.ts (145 lines) — P&L summary aggregation
• api/admin/business-planning/expansion/markets/route.ts (110 lines) — city rankings
• sizing-guide-a4.tsx (0 bytes, unreferenced)
• sizing-guide-us-letter.tsx (0 bytes, unreferenced)

AI Intelligence Layer — full transparency pipeline

• provenance.ts: Data source tracking, metric snapshot recording with 24h dedup
• collectors/world-bank.ts: GDP growth + tourism arrivals from World Bank API
• Analysis: strong/moderate/slow/contracting thresholds with confidence decay
• collectors/exchange-rates.ts: ECB rates with static fallback for 22 currencies
• Analysis: pegged currency detection, FX risk assessment
• collectors/overpass-luxury.ts: OSM luxury brand density (22 brands by Wikidata ID)
• Analysis: 5km radius, proxy index formula, mapping coverage confidence
• extractors/structured-extract.ts: GPT-4o structured extraction engine
• Enforces transparency: reasoning, evidence quotes, confidence notes
• extractors/rent-extractor.ts: AI rent benchmark extraction from real estate reports
• Specificity-based confidence: exact corridor vs city vs regional
• scoring/run-scoring.ts: Weighted scoring with min-max normalization
• Full factor breakdown: strengths, weaknesses, interpretations per metric
• Rank change detection vs prior run
• scoring/detect-anomalies.ts: 5 anomaly detection rules
• RANK_MOVEMENT, METRIC_SPIKE, CONFIDENCE_EROSION, DATA_STALENESS, NEW_ENTRANT
• scoring/generate-insights.ts: GPT-4o-mini weekly narrative reports
• Executive summary, opportunities, risks, action items with priorities
• Graceful fallback to structured-only report if AI unavailable
• index.ts: 6-phase orchestrator (collect → extract → score → detect → generate → store)
• Graceful degradation: each phase independent, partial results preserved
• api/cron/expansion-intelligence/route.ts: Weekly cron endpoint (Sunday 2am UTC)
• CRON_SECRET auth, skip flags, concise response summaries
• vercel.json: Added expansion-intelligence cron schedule
• determination: human-readable explanation of what this means
• factors[]: specific data points that drove the conclusion
• confidence: numerical score with documented decay rules
• evidence: source URLs, data years, extraction quotes

Monster v2 — Business Planning + Retail Expansion Intelligence

• P&L Overview with expense CRUD, revenue targets, real-time summary
• Forecasting with scenario modeling (3 pre-built scenarios + growth slider)
• Budget tracking by department with utilization %
• KPI Scorecards with RAG status (GREEN/AMBER/RED) and trend indicators
• Strategy & OKRs with objectives, key results, and initiatives
• Reports page (investor update, monthly review, tax prep templates)
• Market Rankings: 50-city scoring engine with configurable weights
• Site Selection: 50 retail corridors with rent benchmarks and filtering
• Store Economics: prototypes, rent/payroll/buildout benchmarks (4-tab view)
• Compliance Matrix: legal, tax, banking profiles for 21 countries
• Rollout Planner: multi-store timeline with runway impact
• 25+ new Prisma models for expansion intelligence
• SQL migration: 512 lines covering all tables
• City seed script: 21 countries, 50 cities, 50 corridors, 100 metric snapshots
• Scoring model (sm_default_v1) with 12 metric definitions
• All 12 API routes use Prisma typed model API (zero raw SQL mismatch risk)
• Business Planning navigation component with responsive desktop/tablet/mobile
• Full auth gating (OWNER/MANAGER only)
• All files verified: 0 TypeScript errors across 28 files

resolve useTranslations missing context error on /admin/cap-table

• The cap-table layout used next-intl's useTranslations() but the /admin
• route tree uses a custom AdminI18nProvider (not NextIntlClientProvider).
• NextIntlClientProvider only existed in the [locale] storefront layout.
• Fix: Split layout.tsx into a server component that reads the admin-locale
• cookie, loads the correct messages JSON, and wraps everything in
• NextIntlClientProvider. All client UI moved to cap-table-layout-client.tsx.
• This fixes the runtime error:
• Failed to call useTranslations because the context from
• NextIntlClientProvider was not found.

scope 'The Monster' — data-driven business planning (6 phases)

• Phase 1: Financial Dashboard & P&L Engine
• Phase 2: Forecasting & Scenario Modeling
• Phase 3: Budgets & Goal Alignment
• Phase 4: KPI Scorecards & Automated Insights
• Phase 5: Strategic Planning & Roadmap (OKRs)
• Phase 6: Business Intelligence Reports & Export

consolidate sidebar nav + CRM appointments tab + contractors section

• Remove Engagement Leads and Appointments from admin sidebar (now sub-tabs under CRM)
• Add Appointments as third tab in CRM (/admin/crm/appointments) with full calendar UI
• Redirect old /admin/appointments route to /admin/crm/appointments
• Update dashboard appointment links to new CRM route
• Add CRM keywords for appointment/engagement search terms
• Create Contractor model in Prisma (type, status, rates, tax/W-9 tracking)
• Add SQL migration for contractors table with enums and indexes
• Create full CRUD API at /api/admin/contractors with auth guards
• Build contractors page at /admin/employees/contractors with:
• Stats dashboard, search, type/status filters
• Create/edit/view dialogs with comprehensive form
• Table with name, type, contact, rates, status, W-9 columns
• Employee tab navigation with Contractors tab
• Add contractor keywords to sidebar search

add educational InfoTip tooltips + Portuguese i18n for all cap-table pages

• Created reusable InfoTip component (HelpCircle icon + Radix Tooltip)
• Added capTable namespace to en.json with 80+ educational tooltip strings
• Added full Portuguese translation of capTable namespace to pt.json
• Added InfoTips to all 12 cap-table pages: layout, overview, ownership, stakeholders, shares, options, convertibles, rounds, events, modeling (5 sub-components), subsidiaries, settings, compliance
• Every financial term (share classes, options, SAFEs, liquidation prefs, vesting, waterfall, dilution, etc.) now has a hover tooltip explaining it

split cap-table monolith (5,366 lines) into 12 separate route pages

• Created shared infrastructure: _lib/types.ts (interfaces, formatters, constants) and _lib/context.tsx (CapTableProvider + useCapTable hook)
• Created layout.tsx with shared header, nav bar, health checks, board approval banner, export dropdown
• Split into separate pages: overview, ownership, stakeholders, shares, options, convertibles, rounds, events, modeling, subsidiaries, settings, compliance
• Each page loads independently at /admin/cap-table/{section} for faster page loads
• Also includes BigInt serialization fix for cap-table API routes (bigint-serialize.ts utility)
• Original monolith preserved as page.tsx.old for reference

organize email marketing by month, fix Select empty value error, add rich text editor for Jewel Vox articles

• Create monthly subfolders (Feb-June 2026) for organized email marketing templates
• Move Valentine's 2026 campaign to february-2026/ subfolder
• Fix Select.Item empty value error in category selector (use 'none' sentinel value)
• Install TipTap rich text editor with formatting, color, alignment, lists, links, and image support
• Add RichTextEditor component with intuitive toolbar (headings, font sizes, bold/italic/underline, colors, alignment, lists, blockquotes, links, image upload/paste)
• Update article form to use RichTextEditor instead of plain textarea
• Add featured image file upload support with preview and remove button
• Improve UX for article creation/editing - mom can now format articles visually

Remove shadow from register form for seamless mosaic integration

• Remove shadow-2xl from the form cell in the mosaic grid
• Form now blends seamlessly with product image tiles
• Desktop only (mobile still has shadow for card elevation)

Clean up register promo page: remove min order + required badge notes

• Remove '(min. $500 order)' from registration description text
• Remove 'Valid on orders over $500' from the gift card banner
• Remove amber 'Required for $100 gift card' badge next to newsletter checkbox
• Remove 'Newsletter subscription is required' helper text
• Newsletter still defaults to checked in promo flow

/admin/products/[id] 404 caused by overly broad redirect rule

• The redirect '/:locale/products/:slug' → '/:locale/creations/:slug' was
• matching /admin/products/[id] because :locale is a wildcard that matched
• 'admin'. This caused admin product detail pages to redirect to the
• non-existent /admin/creations/[id] → 404.
• Fix: Constrain :locale to only match actual 2-letter locale codes using
• a regex pattern in the redirect source.

Address 3 non-critical GSC Product snippet issues

• Add priceValidUntil (end of current year) to Offer structured data
• Add aggregateRating support to Product schema (auto-populates when reviews exist)
• Add reviewCount + averageRating to ProductData interface
• Fetch review stats from DB on product pages for structured data
• Clean up check-products script

Remove One-of-One Creation scarcity badge from product pages

• Remove the amber badge with star icon from product detail pages
• Remove unused oneOfOneCreation translation key
• Keep the Handcrafted · Unique · Made with Love tagline (still in use)

remove Buy Now button, WhatsApp international-only + black styling, update audit checkboxes

• Remove Buy Now button from ProductActions (redundant — Add to Bag already goes to cart)
• Remove buyNow translation key, Zap/useRouter/useCart/isBuyingNow dead code
• WhatsApp button: only shows for international visitors (hidden when English + USD)
• WhatsApp button: black luxury styling (bg-stone-900) instead of green
• Update SALES_CONVERSION_AUDIT.md: check off completed items (Meta Pixel, GSC, social proof, exit-intent, scarcity badges, abandoned cart, WhatsApp)

Sales conversion audit: Buy Now, social proof, exit-intent, Meta Pixel, WhatsApp, cart recovery toggle

• Added 'BUY NOW' button on product pages (adds to cart + redirects to /cart)
• Styled as outline button below Add to Bag for clear visual hierarchy
• New /api/products/[id]/social-proof endpoint using real ProductView data
• Shows 'X people have recently viewed this piece' (monthly, weekly if >100, capped at 100+)
• New ProductSocialProof client component with fade-in animation
• Added exit-intent detection to EmailSignupPopup (desktop only)
• Triggers when mouse leaves viewport from top, with 3s debounce
• Still falls back to 7-second timer trigger
• Added 'One-of-One Creation' amber badge for handmade products near price
• Added 'Handcrafted · Unique · Made with Love' tagline below description
• Enhanced handmade section prominence
• Added Meta Pixel script to root layout (env-gated, production only)
• Created src/lib/tracking/meta-pixel.ts utility with all standard events
• ViewContent tracking on product pages via MetaPixelProductTracker
• AddToCart tracking in cart context
• Updated CSP to allow connect.facebook.net
• Added metadata.verification.google support via NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION env var
• New floating WhatsApp button on all storefront pages
• Dismissible tooltip, links to wa.me with pre-filled message
• GET/POST /api/admin/marketing/cart-recovery toggle API
• SiteSetting check in abandoned-carts cron (disabled by default)
• Admin UI toggle with Switch component on system emails page
• Added 'automation' category to admin settings

collection pages crashing - serialize Date objects and remove isPrimary filter

• CRITICAL FIX: All collection detail pages (/collections/pearl-necklaces, /collections/izzy, etc.) were showing 'Oops Something went wrong' error. Root causes: 1. Passing Date objects from server component to client component (createdAt field)
• now serialized to ISO string 2. isPrimary image filter was too restrictive
• products without a primary image flag got no images, causing render issues 3. Added try/catch to getCollection to prevent unhandled exceptions This was the direct cause of 0 sales from the Brevo email campaign (54 clickers all hit broken collection page).

Fix cap-table 500: parallel queries, non-fatal audit log, maxDuration, timing diagnostics

• Run all 10 cap-table queries in parallel via Promise.all (was sequential)
• Fix logAudit: use $executeRaw instead of $queryRaw for INSERT, wrap in try-catch (non-fatal)
• Add maxDuration=30 for Vercel function timeout
• Add per-query timing diagnostics in response._debug
• Root cause: sequential queries + PgBouncer pool_timeout=20s + Vercel 10s default timeout

Convert Decimal to Number in promotion discountValue for client serialization

• Prisma Decimal objects cannot be passed to React Client Components
• Added Number() conversion for discountValue in activePromotions mapping
• This fixes the 'Decimal objects are not supported' serialization error on /admin dashboard