diff --git a/apps/dashboard/README.md b/apps/dashboard/README.md
index 7db9ff9..c1108d5 100644
--- a/apps/dashboard/README.md
+++ b/apps/dashboard/README.md
@@ -15,6 +15,20 @@ pnpm dev
 
 Open [http://localhost:3000](http://localhost:3000) in your browser.
 
+## Setup & Build Process
+
+### Path Aliases
+To share code across the monorepo, the dashboard uses TypeScript path aliases. In `tsconfig.json`, the `@guildpass/*` alias is mapped to `../../packages/*`. This allows importing from monorepo packages (e.g. `@guildpass/env`, `@guildpass/metrics`) without relative paths.
+
+### Build Order
+Next.js requires workspace packages to be available during its build. 
+1. Upstream packages (like `@guildpass/env`) build their outputs to `dist/` first.
+2. The Next.js dashboard uses `transpilePackages` in `next.config.mjs` to include the workspace packages in the build pipeline.
+3. The dashboard is built to `.next/`.
+
+### Required Environment
+If you are using `DASHBOARD_STORAGE_MODE=durable`, you must provide a valid `DATABASE_URL` during build and runtime. For local development, copy the `.env.example` to `.env.local`.
+
 ---
 
 ## Available Routes
diff --git a/apps/dashboard/next.config.mjs b/apps/dashboard/next.config.mjs
index 2bad752..e6dd553 100644
--- a/apps/dashboard/next.config.mjs
+++ b/apps/dashboard/next.config.mjs
@@ -5,6 +5,7 @@ const nextConfig = {
     "@guildpass/env",
     "@guildpass/integration-client",
     "@guildpass/webhook-utils",
+    "@guildpass/metrics",
   ],
 
   // ── Production optimisations ──────────────────────────────────────
diff --git a/apps/dashboard/tsconfig.json b/apps/dashboard/tsconfig.json
index e35ba31..18e9e31 100644
--- a/apps/dashboard/tsconfig.json
+++ b/apps/dashboard/tsconfig.json
@@ -24,9 +24,7 @@
     "ignoreDeprecations": "5.0",
     "paths": {
       "@/*": ["./*"],
-      "@guildpass/env": ["../../packages/env/dist/index.d.ts"],
-      "@guildpass/integration-client/*": ["../../packages/integration-client/*"],
-      "@guildpass/mock-repositories": ["../../packages/integration-client/mock/mockRepositories"]
+      "@guildpass/*": ["../../packages/*"]
     }
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],