chore: prepare Delivera Vercel preview deploy

.claude/settings.json

@@ -8,7 +8,16 @@
       "Bash(SKIP_WEBSERVER=true npx playwright test --max-failures=99 --workers=1 --reporter=list)",
       "Bash(tasklist /FI \"IMAGENAME eq node.exe\")",
       "PowerShell(Get-Process node -ErrorAction SilentlyContinue)",
-      "Bash(SKIP_WEBSERVER=true npx playwright test \"tests/Delivera-UX-19-DirectValue-Improvements-Validation-Tests.spec.js\" \"tests/Delivera-Current-Sprint-Intervention-Queue-Validation-Tests.spec.js\" --reporter=line)"
+      "Bash(SKIP_WEBSERVER=true npx playwright test \"tests/Delivera-UX-19-DirectValue-Improvements-Validation-Tests.spec.js\" \"tests/Delivera-Current-Sprint-Intervention-Queue-Validation-Tests.spec.js\" --reporter=line)",
+      "Bash(Get-ChildItem -Path \"c:\\\\Shared\\\\Projects\\\\Delivera\" -Force)",
+      "Bash(Select-Object Name, Mode)",
+      "Bash(npx jest *)",
+      "Bash(findstr /i \"test\\\\|jest\\\\|script\")",
+      "Bash(Get-Content \"C:/Users/oka/AppData/Local/Temp/claude/c--Shared-Projects-Delivera/0b948dbe-143a-4893-ba59-a22c8d2173c0/tasks/blc5yzl9j.output\" -Tail 5)",
+      "PowerShell(\\(Get-Item \"C:/Users/oka/AppData/Local/Temp/claude/c--Shared-Projects-Delivera/0b948dbe-143a-4893-ba59-a22c8d2173c0/tasks/blc5yzl9j.output\"\\).Length)",
+      "PowerShell(Get-Process -Name \"node\" -ErrorAction SilentlyContinue)",
+      "Bash(git push *)",
+      "PowerShell($f = 'C:\\\\Users\\\\oka\\\\AppData\\\\Local\\\\Temp\\\\claude\\\\c--Shared-Projects-Delivera\\\\0b948dbe-143a-4893-ba59-a22c8d2173c0\\\\tasks\\\\biut389yv.output'; $lines = Get-Content $f; \"Total lines: $\\($lines.Count\\)\"; $lines | Select-Object -Last 10)"
     ]
   }
 }

.github/workflows/ci.yml

@@ -23,6 +23,10 @@ jobs:
       - run: npm run test:all
         env:
           CI: true
+          NODE_ENV: test
+          JIRA_HOST: https://example.atlassian.net
+          JIRA_EMAIL: ci-placeholder@example.com
+          JIRA_API_TOKEN: ci-placeholder-token
 
   deploy:
     needs: test

.github/workflows/vercel-preview.yml

@@ -0,0 +1,32 @@
+name: Vercel Preview
+
+on:
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  vercel-preview:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build:css && npm run check:css
+      - name: Skip deploy when Vercel secrets are not configured
+        if: ${{ env.VERCEL_TOKEN == '' || env.VERCEL_ORG_ID == '' || env.VERCEL_PROJECT_ID == '' }}
+        run: |
+          echo "Vercel preview skipped: configure VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID repository secrets."
+      - name: Deploy preview to Vercel
+        if: ${{ env.VERCEL_TOKEN != '' && env.VERCEL_ORG_ID != '' && env.VERCEL_PROJECT_ID != '' }}
+        run: |
+          npx vercel pull --yes --environment=preview --token "$VERCEL_TOKEN"
+          npx vercel build --token "$VERCEL_TOKEN"
+          npx vercel deploy --prebuilt --token "$VERCEL_TOKEN"

README.md

@@ -1,153 +1,127 @@
 # Delivera
 
-Delivery intelligence for scrum teams and leaders, backed by Jira data.
+Delivery intelligence for scrum teams and leaders, backed by Jira.
 
-Delivera focuses on three primary surfaces:
+Delivera answers **what to say, who to chase, and what proof to show** — in about 10 seconds on the Brief.
 
-- ` /report` for portfolio and performance reporting
-- ` /current-sprint` for squad mission-control transparency
-- ` /leadership` for leadership HUD and trend visibility
+## Primary surfaces
 
-## Quickstart
+| Route | Surface | Purpose |
+|-------|---------|---------|
+| `/governance` | **Brief** | Delivery answer, owner actions, PI confidence, agent queue |
+| `/current-sprint` | **Sprint** | What must move today (blockers, owners, nudges) |
+| `/report` | **Proof** | Evidence and drill-down for the current Brief |
 
-### Prerequisites
+**Bookmarks:** `/brief` → `/governance`. `/leadership` and `/program-increment` → `/governance#decision-snapshot`. `/value-delivery` → `/report`. `/teams` and `/risks-blockers` → `/current-sprint` (with `#stuck-card` where applicable).
 
-- Node.js `>=20`
-- Jira access credentials (`JIRA_HOST`, `JIRA_EMAIL`, `JIRA_API_TOKEN`)
+Root `/` lands on Brief when auth is off; otherwise follows your configured auth landing.
 
-### Install
+## Global chrome
 
-```bash
-npm install
-```
+Authenticated pages use a Jira-style top bar (`#app-top-chrome`, `Delivera-Shared-Top-Chrome-01Render-UI.js`):
 
-### Configure env
+- **Brief · Sprint · Proof** surface switcher (primary wayfinding)
+- Sidebar toggle, workspace context, search, **Create**, notifications, help, settings, avatar
+- Left sidebar: context card + data pulse only (nav links hidden on desktop)
+- Duplicate page-level **Create** buttons are suppressed when top chrome is present
 
-Copy `.env.example` to `.env` and set at least:
+Notifications mount in `#app-notification-slot` under the top bar (`Delivera-Shared-Notifications-Dock-Manager.js`).
 
-```bash
-JIRA_HOST=https://your-domain.atlassian.net
-JIRA_EMAIL=your.email@company.com
-JIRA_API_TOKEN=your_jira_api_token
-```
+## Brief highlights
 
-### Run locally
+- Shared project catalog (`Delivera-Shared-Projects-Catalog-01SSOT.js`, `GET /api/projects-catalog.json`)
+- Cache-first governance APIs; **Refresh** bypasses cache where supported
+- Above-fold order: answer → owner clusters → setup debt → verdict → PI strip; agent queue and feedback in collapsed `<details>`
+- PI baseline wizard with optional slide upload (OpenAI/Claude keys in Settings or `.env`)
+- Inbox drawer with icon tabs; guided nudge review (not silent approve)
 
-```bash
-npm run dev
-```
+Details: [`context.md`](context.md), governance tests via `npm run test:journey:governance`.
+
+## Quickstart
 
-or production-style startup:
+**Prerequisites:** Node.js `>=20`, Jira credentials.
 
 ```bash
-npm start
+npm install
+cp .env.example .env   # set JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN
+npm run dev            # or npm run dev:hot for CSS watch + nodemon
 ```
 
-`npm start` runs CSS build first via `prestart`.
+Production-style: `npm start` (runs `build:css` first).
 
-## Access and Auth Modes
+Playwright against an already-running server:
 
-Delivera supports three runtime modes:
-
-- **No auth (default local loop):** when legacy auth variables are not set, `/` redirects to report.
-- **Legacy auth:** enable with `SESSION_SECRET`, `APP_LOGIN_USER`, `APP_LOGIN_PASSWORD`.
-- **SuperTokens auth:** enable with `SUPERTOKENS_ENABLED=true`; hybrid migration is supported with `SUPERTOKENS_HYBRID_MODE=true`.
-
-Detailed env matrix: [`docs/environment.md`](docs/environment.md)
-
-## Common Commands
-
-### Build and run
-
-- **One dev port (recommended):** set `PORT=3001` once in `.env`, then run `npm run dev:hot` — nodemon restarts the API on file save and CSS partials rebuild automatically (no second terminal on 3003).
-- `npm run dev` — build CSS once, then nodemon (same hot API restart; run `npm run build:css` after stylesheet edits if not using `dev:hot`).
-- `npm start` — production-style start (prebuilds CSS).
-- Playwright against your running server: `BASE_URL=http://localhost:3001 SKIP_WEBSERVER=true npm run test:current-sprint:dedupe-fold`
-- `npm run build:css`
-- `npm run check:css`
-- `npm run validate:jira-env`
+```bash
+npm start
+# another terminal:
+BASE_URL=http://localhost:3000 SKIP_WEBSERVER=true npm run test:smoke
+```
 
-### Testing
+## Auth modes
 
-- Full orchestration: `npm run test:all`
-- Smoke: `npm run test:smoke`
-- Current Sprint journey: `npm run test:journey:current-sprint`
-- Leadership journey: `npm run test:journey:leadership`
-- Outcome intake journey: `npm run test:journey:outcome-intake`
-- UX core journey: `npm run test:journey:ux-core`
-- Direct-value Jira send (Current Sprint): `npm run test:journey:direct-value-send`
-- Human nudge review + Settings activity: `npm run test:journey:human-nudge-trust`
-- Viewport declutter (stories before cockpit): `npm run test:journey:viewport-declutter`
-- Data integrity journey: `npm run test:journey:data-integrity`
-- Full E2E journey bucket: `npm run test:e2e:full`
-- Stop orchestration: `npm run test:all:stop`
+- **No auth (local default):** open Brief without login vars
+- **Legacy:** `SESSION_SECRET`, `APP_LOGIN_USER`, `APP_LOGIN_PASSWORD`
+- **SuperTokens:** `SUPERTOKENS_ENABLED=true` (optional `SUPERTOKENS_HYBRID_MODE=true`)
 
-For run modes, fail-fast behavior, and impacted-only flags, see [`TESTING.md`](TESTING.md).
+Full matrix: [`docs/environment.md`](docs/environment.md)
 
-## Latest UX and Trust Hardening
+## Common commands
 
-- Decision-first behavior was tightened across `report`, `current-sprint`, and `leadership` without adding new flows.
-- Report header refresh now uses one preview dispatch path with explicit status messaging for busy, success, and retry states.
-- Current Sprint now exposes a top intervention shortlist in the sticky header to reduce standup hunt time.
-- Leadership confidence messaging now prioritizes stale/partial state clarity so trust risk is explicit before action.
-- Contrast/readability improvements were applied to report action status, context strips, sprint action chips, and leadership summary text.
-- New Playwright fail-fast validations were added for refresh trust, shortlist action rhythm, cross-surface freshness SSOT, duplicate UI regression, and mobile leadership first-viewport clarity.
-- Current Sprint can post guided nudges to Jira via `POST /api/issues/:issueKey/comment` (Send to Jira, top nudge, Take action). Restart the local server after pulling API changes — a stale process returns `Cannot POST /api/issues/.../comment`.
-- Focused direct-value + Jira send gate: `npm run test:journey:direct-value-send`
-- Current Sprint viewport lean: stories and work table render before the collapsed decision cockpit; jump links and role lens live in the header drawer; human nudge uses review-before-send (`npm run test:journey:human-nudge-trust`, `npm run test:journey:viewport-declutter`).
-- Sprint at-a-glance briefing (SSOT `Delivera-CurrentSprint-Summary-03AtAGlance-Briefing-SSOT.js`): header mission strip and quick copy include time left, top stale item with hours/owner, and a concrete next action; Jira comments support `@displayName` mentions when `meta.teamRoster` is present on the sprint payload.
-- Risk vocabulary SSOT (`Delivera-CurrentSprint-Risk-Vocabulary-01Terms-SSOT.js`): UI says “stale in progress” once (not “blockers” in 20 places); viewport-lean header hides duplicate chips when the mission briefing is visible.
-- Sidebar IA (3 primaries): **Current Sprint**, **Delivery**, **Leadership**; **Today**, **Risks** (deep link `#stuck-card`), **Teams**, **PI Goals**, **Value Archive**, and **Settings** live under **More**. Shell routes `/risks-blockers` and `/teams` redirect into sprint. Sidebar **Context** shows live sprint scope on `/current-sprint` (not “No report run yet”). Mission briefing risk line is one-click scroll + filter.
+| Command | Use |
+|---------|-----|
+| `npm run build:css` | Compile `public/css/*` → `public/styles.css` |
+| `npm run check:css` | Fail if `styles.css` is out of sync |
+| `npm run validate:jira-env` | Probe Jira `/myself` with `.env` |
+| `npm run dev:hot` | Single-port dev with CSS + API reload |
+| `npm run test:all` | Full fail-fast orchestration |
+| `npm run test:smoke` | Short UX smoke |
+| `npm run test:current-sprint:dedupe-fold` | Sprint header/viewport gate |
+| `npm run test:journey:governance` | Brief / governance Playwright bundle |
+| `npm run test:journey:ux-core` | Cross-surface UX gate |
+| `npm run vercel:deploy` | Manual Vercel deploy after `vercel login` |
 
-### Local dev without port churn (CI/CD-friendly patterns)
+Orchestration, journeys, and `SKIP_WEBSERVER`: [`TESTING.md`](TESTING.md)
 
-1. **`npm run dev:hot`** — single `PORT` in `.env`; nodemon + CSS watch (near-zero downtime for API; hard refresh browser after JS module graph changes).
-2. **`SKIP_WEBSERVER=true` + `BASE_URL`** — Playwright hits your already-running instance instead of spawning another port.
-3. **Production:** Render blueprint / `npm start` with health checks; blue-green or rolling deploy on the host — see [`docs/deployment.md`](docs/deployment.md).
+## CSS contract
 
-## Documentation Map
+Edit partials under `public/css/` only. Never edit `public/styles.css` directly.
 
-- Environment details: [`docs/environment.md`](docs/environment.md)
-- Deployment details: [`docs/deployment.md`](docs/deployment.md)
-- API contracts: [`docs/api-reference.md`](docs/api-reference.md)
-- Troubleshooting: [`docs/troubleshooting.md`](docs/troubleshooting.md)
-- Release notes: [`docs/release-notes.md`](docs/release-notes.md)
-- README migration map: [`docs/readme-migration-map.md`](docs/readme-migration-map.md)
+```bash
+npm run build:css
+npm run check:css
+```
 
-## Doc Ownership (SSOT)
+Ownership: [`public/css/README.md`](public/css/README.md)
 
-- **Testing contracts and orchestration flags:** [`TESTING.md`](TESTING.md)
-- **CSS source/build ownership:** [`public/css/README.md`](public/css/README.md)
-- **Architecture and module context:** [`context.md`](context.md)
-- **Operational onboarding index:** this `README.md`
+## Deployment
 
-## Architecture At A Glance
+- **Render:** [`render.yaml`](render.yaml) — always-on Node, background workers
+- **Vercel:** `api/index.js` + `vercel.json` — serverless Express; workers disabled
 
-- Server entrypoint: [`server.js`](server.js)
-- Express app factory: [`lib/Delivera-Express-Core-App-Factory-Handler.js`](lib/Delivera-Express-Core-App-Factory-Handler.js)
-- Route surfaces:
-  - Views: [`routes/views.js`](routes/views.js)
-  - API: [`routes/api.js`](routes/api.js)
-- Frontend modules and pages:
-  - `public/*.html`
-  - `public/Delivera-*.js`
-  - `public/css/*.css` (compiled to `public/styles.css`)
+Pre-deploy: `npm run build:css`, `npm run check:css`, then your chosen test gate.
 
-## Deployment
+**Vercel note:** If deploy fails with `functions.api/index.js.includeFiles should be string`, clear any **Functions** override in the Vercel project dashboard so git `vercel.json` is authoritative.
 
-Deploy to Node hosts such as Render or Vercel.
+Full guide: [`docs/deployment.md`](docs/deployment.md)
 
-- Render blueprint: [`render.yaml`](render.yaml)
-- Full deployment guidance: [`docs/deployment.md`](docs/deployment.md)
+## Documentation
 
-## Troubleshooting
+| Topic | Doc |
+|-------|-----|
+| Environment | [`docs/environment.md`](docs/environment.md) |
+| Deployment | [`docs/deployment.md`](docs/deployment.md) |
+| API | [`docs/api-reference.md`](docs/api-reference.md) |
+| Troubleshooting | [`docs/troubleshooting.md`](docs/troubleshooting.md) |
+| Release history | [`docs/release-notes.md`](docs/release-notes.md) |
+| Testing | [`TESTING.md`](TESTING.md) |
+| Architecture | [`context.md`](context.md) |
 
-Start with [`docs/troubleshooting.md`](docs/troubleshooting.md) for:
+## Architecture (short)
 
-- Port conflicts (`EADDRINUSE`)
-- Jira auth/connectivity failures
-- CSS build/check drift
-- Test orchestration failures
+- Entry: [`server.js`](server.js)
+- App factory: [`lib/Delivera-Express-Core-App-Factory-Handler.js`](lib/Delivera-Express-Core-App-Factory-Handler.js)
+- Routes: [`routes/views.js`](routes/views.js), [`routes/api.js`](routes/api.js)
+- UI: `public/*.html`, `public/Delivera-*.js`, compiled `public/styles.css`
 
 ## License
 

api/index.js

@@ -1,11 +1,10 @@
+import dotenv from 'dotenv';
 import { createDeliveraExpressCoreApp } from '../lib/Delivera-Express-Core-App-Factory-Handler.js';
-import { appEnvConfig } from '../lib/Delivera-Config-Env-Services-Core-SSOT.js';
 
-const app = createDeliveraExpressCoreApp({
-  port: appEnvConfig.port,
-  enableBackgroundWorkers: false,
-});
+// Vercel serverless entrypoint. Keep background workers off in serverless so
+// scheduled snapshot work is not duplicated on short-lived function invocations.
+dotenv.config();
 
-export default function handler(req, res) {
-  return app(req, res);
-}
+const app = createDeliveraExpressCoreApp({ enableBackgroundWorkers: false });
+
+export default app;