[Docs]: comprehensive audit reconciliation and monorepo sync

.github/workflows/builds.yaml

@@ -48,5 +48,8 @@ jobs:
       - name: Mock Portfolio Template Library
         run: node scripts/mock-template-library.mjs
 
+      - name: Build Shared Packages
+        run: npm run build -w @veriworkly/profile-core --if-present
+
       - name: Build Application
         run: npm run build -w ${{ matrix.workspace }}

.github/workflows/tests.yaml

@@ -35,6 +35,9 @@ jobs:
       - name: Prisma Generate
         run: npm exec -w @veriworkly/server -- prisma generate --schema=prisma/schema.prisma
 
+      - name: Build Shared Packages
+        run: npm run build -w @veriworkly/profile-core --if-present
+
       - name: Run Backend Tests
         run: npm run test -w @veriworkly/server --if-present
 
@@ -73,6 +76,9 @@ jobs:
       - name: Install Dependencies
         run: npm ci --legacy-peer-deps
 
+      - name: Build Shared Packages
+        run: npm run build -w @veriworkly/profile-core --if-present
+
       - name: Run Studio Tests
         run: npm run test:contracts -w @veriworkly/studio --if-present
 
@@ -92,6 +98,9 @@ jobs:
       - name: Install Dependencies
         run: npm ci --legacy-peer-deps
 
+      - name: Build Shared Packages
+        run: npm run build -w @veriworkly/profile-core --if-present
+
       - name: Mock Portfolio Template Library
         run: node scripts/mock-template-library.mjs
 

CONTRIBUTING.md

@@ -5,7 +5,7 @@ First off, thank you for considering contributing to **VeriWorkly**! We are buil
 > [!IMPORTANT]
 > **Detailed guides, developer workflows, and coding standards** live in our official documentation:
 >
-> - 📖 **[Full Contributing Guidelines](https://docs.veriworkly.com/docs/contributing/index)**
+> - 📖 **[Full Contributing Guidelines](https://docs.veriworkly.com/docs/contributing)**
 > - 🛠️ **[Detailed Local Setup Guide](https://docs.veriworkly.com/docs/getting-started/local-setup)**
 
 ---
@@ -36,7 +36,7 @@ Before getting started, please **star our repository** to show your support for
 2. Clone your fork locally:
    ```bash
    git clone https://github.com/YOUR_USERNAME/veriworkly.git
-   cd veriworkly-resume
+   cd veriworkly
    ```
 3. Set up the upstream remote:
    ```bash
@@ -61,10 +61,10 @@ Before getting started, please **star our repository** to show your support for
 ### 5. Local Setup & Verification 🛠️
 
 - Install dependencies: `npm install`
-- Copy environment variables: `cp .env.example .env` and `cp apps/server/.env.example apps/server/.env`
+- Copy environment variables: copy all `.env.example` files to `.env` in root and across `apps/` (see `ENV_SETUP.md` or `QUICK_START.md`).
 - Run the app locally to test your changes:
   - **Frontend-only (Site/Templates at port 3000)**: `npm run dev`
-  - **Full-stack (All apps/databases)**: `npm run dev:all` _(Requires running `npm run db:push -w @veriworkly/server`)_
+  - **Full-stack (All apps/databases)**: `npm run dev:all` _(Requires running `npm run db:push && npm run db:generate`)_
 
 ---
 

ENV_SETUP.md

@@ -1,28 +1,69 @@
 # Environment Variables Configuration
 
-VeriWorkly requires specific environment variables to function correctly across the frontend and backend.
+VeriWorkly uses a multi-app monorepo structure where each application and the root workspace define specific `.env.example` templates.
 
-## 🔑 Critical Variables
+---
 
-### Backend (`apps/server/.env`)
+## 🔑 Workspace Environment Configurations
 
-- `DATABASE_URL`: PostgreSQL connection string.
-- `AUTH_SECRET`: Random secure string for authentication.
-- `AUTH_SMTP_HOST`, `AUTH_SMTP_PORT`, `AUTH_SMTP_USER`, `AUTH_SMTP_PASS`: For sending OTP emails.
-- `REDIS_URL`: (Optional) For rate limiting and API caching.
+### 1. Root Monorepo (`.env`)
 
-### Frontend Studio (`apps/studio/.env`)
+- `NODE_ENV`: Runtime environment (`development`, `production`, `test`).
+- `PORT`: Port bindings for multi-workspace coordination.
 
-- `NEXT_PUBLIC_BACKEND_URL`: URL of the backend server (default: `http://localhost:8080/api/v1`).
-- `NEXT_PUBLIC_APP_URL`: URL of the studio app (default: `http://localhost:3001`).
-- `AUTH_SECRET`: Same secret as backend.
+### 2. Backend Server (`apps/server/.env`)
 
-### Marketing Site (`apps/site/.env`)
+- `DATABASE_URL`: PostgreSQL connection string (supports Neon / Supabase / local PostgreSQL).
+- `AUTH_SECRET`: Random 32+ character secure secret for Better-Auth encryption.
+- `REDIS_URL`: **Required.** Backs Better-Auth secondary session storage, API rate limiting, ATS and profile import quotas, view count buffers, and distributed cron job locks.
+- `AUTH_SMTP_HOST`, `AUTH_SMTP_PORT`, `AUTH_SMTP_USER`, `AUTH_SMTP_PASS`, `AUTH_SMTP_FROM`: SMTP credentials for passwordless email OTP authentication.
+- `ADMIN_EMAIL`: Email address of the administrative superuser.
+- `DODO_PAYMENTS_API_KEY`, `DODO_PAYMENTS_WEBHOOK_KEY`: Dodo Payments API and webhook credentials.
+- `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_PUBLIC_URL`: Cloudflare R2 bucket credentials for portfolio media asset uploads.
+- `AI_GATEWAY_AUTH_TOKEN`: Private API token for frontier LLM routing.
 
-- `NEXT_PUBLIC_BACKEND_URL`: URL of the backend server.
-- `NEXT_PUBLIC_APP_URL`: URL of the marketing site (default: `http://localhost:3000`).
+### 3. Builder Studio (`apps/studio/.env`)
 
-## 📚 Detailed Variable Reference
+- `SITE_URL`: Marketing site base URL (default: `http://localhost:3000`).
+- `NEXT_PUBLIC_BACKEND_URL`: Public API endpoint for browser calls (default: `http://localhost:8080/api/v1`).
+- `BACKEND_INTERNAL_URL`: Server-side API endpoint for Next.js SSR requests (default: `http://localhost:8080/api/v1`).
+- `NEXT_PUBLIC_PORTFOLIO_URL`: Portfolio builder workspace URL (default: `http://localhost:3004`).
+- `ADMIN_EMAIL`: Matches server admin email for admin UI surfaces.
+- `AUTH_SECRET`: Matches server auth secret.
 
-For a full list of all available configuration options and their defaults, visit:
+### 4. Marketing Site (`apps/site/.env`)
+
+- `NEXT_PUBLIC_SITE_URL` / `SITE_URL`: Canonical public site origin (default: `http://localhost:3000`).
+- `NEXT_PUBLIC_BACKEND_URL`: Public API endpoint (default: `http://localhost:8080/api/v1`).
+- `BACKEND_INTERNAL_URL`: Server-side API endpoint (default: `http://localhost:8080/api/v1`).
+- `ADMIN_EMAIL`: Admin email for checkout/pricing preview bypass.
+- `AFFILIATE_PROGRAM_ENABLED`, `AMBASSADOR_PROGRAM_ENABLED`: Boot-time feature flags for growth programs.
+
+### 5. Portfolio Builder (`apps/portfolio/.env`)
+
+- `SITE_URL`: Public origin for portfolio app (default: `http://localhost:3004`).
+- `NEXT_PUBLIC_PORTFOLIO_URL`: Studio app URL (default: `http://localhost:3001`).
+- `NEXT_PUBLIC_BACKEND_URL`: Public API endpoint (default: `http://localhost:8080/api/v1`).
+- `BACKEND_INTERNAL_URL`: Server-side API endpoint (default: `http://localhost:8080/api/v1`).
+- `ADMIN_EMAIL`: Admin email for checkout/publish staging gate bypass.
+- `PORTFOLIO_REVALIDATE_SECRET`: Secret token for Next.js on-demand ISR revalidation.
+
+### 6. Documentation Platform (`apps/docs-platform/.env`)
+
+- `SITE_URL`: Docs origin URL (default: `http://localhost:3002`).
+- `NEXT_PUBLIC_BACKEND_URL`: Public API endpoint (default: `http://localhost:8080/api/v1`).
+- `BACKEND_INTERNAL_URL`: Server-side API endpoint (default: `http://localhost:8080/api/v1`).
+- `ALLOWED_ORIGINS`: Allowed origins for API proxy.
+
+### 7. Blog Platform (`apps/blog-platform/.env`)
+
+- `SITE_URL`: Blog origin URL (default: `http://localhost:3003`).
+- `NEXT_PUBLIC_BACKEND_URL`: Public API endpoint (default: `http://localhost:8080/api/v1`).
+- `BACKEND_INTERNAL_URL`: Server-side API endpoint (default: `http://localhost:8080/api/v1`).
+
+---
+
+## 📚 Complete Operations Reference
+
+For exhaustive configuration parameters, defaults, and deployment guides, visit:
 [Environment Variables Guide - VeriWorkly Docs](https://docs.veriworkly.com/docs/operations/environment-variables)

PRODUCT.md

@@ -30,4 +30,4 @@ Avoid surveillance-heavy resume SaaS, generic chatbot interfaces, opaque AI gene
 
 ## Accessibility & Inclusion
 
-Target WCAG 2.1 AA. All editor actions require keyboard access, visible focus, readable contrast, non-color status cues, and reduced-motion-compatible feedback.
+Target WCAG 2.2 Level AA. All editor actions require keyboard access, visible focus, readable contrast, non-color status cues, and reduced-motion-compatible feedback.

QUICK_START.md

@@ -1,14 +1,14 @@
 # Quick Start Guide
 
-VeriWorkly is a monorepo consisting of a Next.js frontend and an Express backend. Follow these steps to get up and running quickly.
+VeriWorkly is a monorepo consisting of 5 Next.js applications (Marketing Site, Studio, Portfolio Builder, Docs, Blog), an Express backend API, and a shared UI library. Follow these steps to get up and running quickly.
 
 ## 📦 Installation
 
 1. **Clone the repository**:
 
    ```bash
    git clone https://github.com/VeriWorkly/veriworkly.git
-   cd veriworkly-resume
+   cd veriworkly
    ```
 
 2. **Install dependencies**:
@@ -22,33 +22,36 @@ VeriWorkly is a monorepo consisting of a Next.js frontend and an Express backend
    ```bash
    cp .env.example .env
    cp apps/server/.env.example apps/server/.env
+   cp apps/studio/.env.example apps/studio/.env
+   cp apps/site/.env.example apps/site/.env
+   cp apps/portfolio/.env.example apps/portfolio/.env
+   cp apps/docs-platform/.env.example apps/docs-platform/.env
+   cp apps/blog-platform/.env.example apps/blog-platform/.env
    ```
 
 4. **Initialize the database**:
+
    ```bash
-   npm run db:push -w @veriworkly/server
+   npm run db:push
+   npm run db:generate
    ```
 
-## 🚀 Running the App
+## 🚀 Running the Apps
 
-To start services (Site, Builder Studio, Backend, Docs, Blog) in development mode:
+To start **all workspaces simultaneously** in development mode:
 
 ```bash
-npm run dev
-npm run dev:site
-npm run dev:studio
-npm run dev:server
-npm run dev:docs
-npm run dev:blog
+npm run dev:all
 ```
 
-To start specific apps:
+To run individual workspaces:
 
-- **Site/Resume**: `npm run dev` (starts @veriworkly/site)
-- **Studio**: `npm run dev:studio`
-- **Server**: `npm run dev:server`
-- **Docs**: `npm run dev:docs`
-- **Blog**: `npm run dev:blog`
+- **Marketing Site** (`http://localhost:3000`): `npm run dev:site` (or `npm run dev`)
+- **Builder Studio** (`http://localhost:3001`): `npm run dev:studio`
+- **Documentation** (`http://localhost:3002`): `npm run dev:docs`
+- **Blog** (`http://localhost:3003`): `npm run dev:blog`
+- **Portfolio Builder** (`http://localhost:3004`): `npm run dev:portfolio`
+- **Backend API Server** (`http://localhost:8080`): `npm run dev:server`
 
 ## 📚 Detailed Documentation
 

README.Local.md

@@ -4,10 +4,10 @@ This guide covers setting up VeriWorkly for local development.
 
 ## Prerequisites
 
-- **Node.js 20+**
-- **npm v10+**
+- **Node.js >= 20.19.0** (Node.js 22 supported)
+- **npm v11+** (`npm@11.16.0`)
 - **PostgreSQL** (We recommend [Neon](https://neon.tech))
-- **Redis** (Local or via Docker)
+- **Redis** (Local or via Docker; required for sessions and locks)
 
 ## Step-by-Step Setup
 
@@ -18,20 +18,22 @@ This guide covers setting up VeriWorkly for local development.
    ```
 
 2. **Environment Configuration**:
-   - Create `.env` in the root.
-   - Create `.env` in `apps/server/`.
-   - See `ENV_SETUP.md` for variable details.
+   - Copy `.env.example` to `.env` in root and across `apps/` (see `ENV_SETUP.md`).
 
-3. **Database Migration**:
+3. **Database Setup**:
 
    ```bash
-   npm run db:push -w @veriworkly/server
+   npm run db:push
+   npm run db:generate
    ```
 
 4. **Start Development Servers**:
    ```bash
-   # Start everything
-   npm run dev
+   # Start all workspaces simultaneously
+   npm run dev:all
+
+   # Or start marketing site only
+   npm run dev:site
    ```
 
 ## 📚 Detailed Guide

README.md

@@ -56,11 +56,11 @@ Instead of mandatory logins and data tracking, VeriWorkly operates on a **local-
 <table width="100%">
   <tr>
     <td align="center" width="50%">
-      <img src="apps/studio/public/templates/resume/precision-ats.svg" alt="Precision ATS" style="border-radius: 8px; border: 1px solid #eaeaea;" width="320" />
+      <img src="apps/studio/public/templates/resume/precision-ats.png" alt="Precision ATS" style="border-radius: 8px; border: 1px solid #eaeaea;" width="320" />
       <br /><strong>Precision ATS</strong>
     </td>
     <td align="center" width="50%">
-      <img src="apps/studio/public/templates/resume/executive-clarity.svg" alt="Executive Clarity" style="border-radius: 8px; border: 1px solid #eaeaea;" width="320" />
+      <img src="apps/studio/public/templates/resume/executive-clarity.png" alt="Executive Clarity" style="border-radius: 8px; border: 1px solid #eaeaea;" width="320" />
       <br /><strong>Executive Clarity</strong>
     </td>
   </tr>
@@ -121,7 +121,7 @@ veriworkly/
 
 ### Prerequisites
 
-- **Node.js**: v20.0.0 or higher
+- **Node.js**: v20.19.0 or higher (Node.js 22 supported)
 - **npm**: Repository uses npm workspaces (`npm install` from root)
 - **PostgreSQL**: Required for backend API functionality ([Neon](https://neon.tech) managed Postgres supported)
 - **Redis**: Required for backend sessions, rate limiting, quotas, and job locking
@@ -200,6 +200,7 @@ npm test -w @veriworkly/server
 
 # Application unit & contract test suites (Vitest)
 npm run test:contracts -w @veriworkly/studio
+npm run test:browser -w @veriworkly/studio
 npm run test:contracts -w @veriworkly/site
 npm test -w @veriworkly/portfolio
 

apps/blog-platform/README.md

@@ -15,7 +15,7 @@ The official blog for VeriWorkly, built with Next.js and Fumadocs.
    npm run dev:blog
    ```
 
-The blog will be available at `http://localhost:3002`.
+The blog will be available at `http://localhost:3003`.
 
 ## ✍️ Content Management
 

apps/blog-platform/content/blog/introducing-the-portfolio-builder.mdx

@@ -39,4 +39,4 @@ Free accounts publish at a shared path (`portfolio.veriworkly.com/portfolio/your
 
 The authenticated workspace — dashboard, editor, analytics, settings — is open to every logged-in user right now. You can build and preview a complete portfolio today, on any account. The one piece still opening up in stages is the publish button and checkout itself, as the launch path finishes getting validated end-to-end. Draft editing is unaffected either way.
 
-Try it from your Studio dashboard — the template gallery is public at veriworkly.com even before you sign in.
+Try it from your Studio dashboard — the portfolio template gallery is public at portfolio.veriworkly.com/templates even before you sign in.

apps/blog-platform/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veriworkly/blog-platform",
-  "version": "3.24.0",
+  "version": "3.24.1",
   "private": true,
   "scripts": {
     "dev": "next dev",

apps/blog-platform/public/llms.txt

@@ -90,6 +90,7 @@ These are labelled separately from career guidance and are written about VeriWor
 - [How the ATS Checker Actually Works](https://blog.veriworkly.com/how-the-ats-checker-actually-works) — deterministic rules engine plus AI analysis layer, shared quota
 - [Introducing the Portfolio Builder](https://blog.veriworkly.com/introducing-the-portfolio-builder)
 - [GitHub vs LinkedIn Import: What's Real, What's AI](https://blog.veriworkly.com/github-vs-linkedin-import-whats-real-whats-ai) — deterministic OAuth mapping versus AI text parsing
+- [How Affiliate & Ambassador Rewards Actually Work](https://blog.veriworkly.com/how-affiliate-and-ambassador-rewards-actually-work) — live 3-tier commission program, campus ambassador application status
 
 ## Citation Guidance for AI Agents
 Career articles on this subdomain are written to be cited independently of the product.