Local development

Oversight is two repositories.

Repo	Purpose	Default port
lending-agent-oversight	The Next.js app (the demo itself)	3000
lending-agent-oversight-docs	The Astro Starlight docs site	4321

Both use pnpm and require no environment variables for v1. Production secrets are documented in Production hardening.

Prerequisites

• Node.js 20 or later
• pnpm 9 or later (npm install -g pnpm)
• Git

Clone

git clone https://github.com/bgood11/lending-agent-oversight.git
git clone https://github.com/bgood11/lending-agent-oversight-docs.git

(Replace with your fork or origin if mirroring.)

Run the app

cd lending-agent-oversight
pnpm install
pnpm dev

The app starts on http://localhost:3000. Hot module reload is enabled. The marketing landing is at /; the demo entry is at /demo/principal.

Useful scripts

pnpm dev            # next dev, port 3000
pnpm build          # production build, output to .next
pnpm start          # serve the production build
pnpm lint           # eslint

Stack

• Next.js 16 (App Router)
• React 19
• Tailwind CSS 4 with @tailwindcss/postcss
• shadcn/ui via @base-ui/react
• Zustand for state
• Motion (Framer Motion successor) for the hero animation
• Geist Sans + Mono for body, Fraunces for display

Run the docs site

cd lending-agent-oversight-docs
pnpm install
pnpm dev

The docs site starts on http://localhost:4321. Astro Starlight handles routing under src/content/docs/*.

Useful scripts

pnpm dev            # astro dev, port 4321
pnpm build          # astro build, output to dist
pnpm preview        # serve the production build

Stack

• Astro 6
• Starlight 0.39
• Sharp for image processing

Run both at once

In separate terminals:

# Terminal A
cd lending-agent-oversight && pnpm dev

# Terminal B
cd lending-agent-oversight-docs && pnpm dev

Or with a multi-pane terminal (tmux, Warp, iTerm split-pane). The two ports do not conflict.

Environment variables

None required for v1. The demo loads no remote data, has no auth, no email, no telemetry.

In production the app reads the following (none of which are needed locally):

Variable	Purpose
DATABASE_URL	Postgres connection string
SESSION_SIGNING_KEY	HMAC key for session cookie signing (rotated quarterly)
POSTMARK_TOKEN	Email delivery
OBJECT_STORE_BUCKET, OBJECT_STORE_REGION, OBJECT_STORE_ACCESS_KEY, OBJECT_STORE_SECRET_KEY	Attachment storage
SENTRY_DSN	Error monitoring
RATE_LIMIT_REDIS_URL	Token-bucket store

See Production hardening for the full list and the rotation policy.

Common local issues

Port already in use

pnpm dev -- -p 3001 to start the app on an alternate port. Astro: pnpm dev -- --port 4322.

pnpm install fails on lockfile mismatch

rm -rf node_modules pnpm-lock.yaml
pnpm install

If the lockfile is committed to the repo, prefer pnpm install --frozen-lockfile=false once, then re-commit.

Tailwind classes not applying

Tailwind 4 uses the new @tailwindcss/postcss plugin. If a class fails to apply, restart pnpm dev. The PostCSS pipeline does not always pick up new files mid-watch.

Hydration mismatch on first load

The demo store is persist-wrapped to localStorage. On first render the server has no localStorage, so a brief client-side hydration runs. The fixture generator is seeded so the rendered set is deterministic; if you see a mismatch, confirm your system clock is correct (the fixture clock is anchored to 2026-05-08T18:00:00Z and computes offsets from Date.now() only for some derived values).

Editor setup

VS Code recommended. The repo carries a .vscode/settings.json (in the app repo) configuring the Tailwind extension and TypeScript-version pinning. The docs repo has no editor config; any Markdown/MDX-aware editor works.