DG-Labs OS

DG-Labs OS is a portfolio presented as a personal operating system - an interface for exploring what DG-Labs thinks about, builds, and ships. The UI leans on familiar OS metaphors (toolbar, dock, windows) but reframes them as a brain-like control panel: a machine of memory, experiments, and evolving ideas.

Documentation

• Product and implementation roadmap: docs/APP_ROADMAP.md
• React + TypeScript event/state guide: docs/REACT_TYPESCRIPT_EVENT_STATE_GUIDE.md
• Archived stabilization completion log: docs/archive/CODEBASE_STABILIZATION_PLAN.md

Features

• Desktop OS UI with a Mac-style toolbar and dock
• Focus-aware desktop menubar (menu sets update by active/focused app)
• Mobile iPhone-inspired lock + home screens (/mobile)
• RippleGrid live background with mouse interaction
• Page-based apps (/apps/notes, /apps/projects, /apps/resume, /apps/terminal)
• Terminal v3 hybrid runtime:
  • deterministic commands (help, open, search, context, sources, etc.)
  • natural-language command router (high-confidence phrase -> deterministic command)
  • retrieval-grounded LLM mode (ask ...) using local knowledge index
  • answer modes (ask, brief, cv, projects)
  • provider selector (openrouter, openai, anthropic, gemini)
  • BYOK support (session-only or optional browser-local persistence)
  • provider health diagnostics via /api/llm/health
  • capability-aware provider fallback (opt-in, only when alternate keys exist)
  • runtime toggles for LLM fallback, provider fallback, router debug, and LLM source footer
• Apple menu "About DG-Labs Pro" window
• Window -> Contact... opens dock Links panel on desktop (email fallback on page routes)
• Modular config in src/config/
• API routes for chat + contact

Current Priority

• Vercel deployment hardening and production runbook execution.
• Agent Runtime v3 UX polish (provider diagnostics, citation compactness, fallback messaging).
• Module cross-link integrity and post-deploy content polish.

Tech Stack

• Astro
• React
• Tailwind CSS
• TypeScript
• Supabase (contact storage)

Getting Started

0. Use the same runtime versions (recommended for reproducibility)

nvm use
pnpm -v
node -v

1. Install dependencies from lockfile

pnpm install --frozen-lockfile

If pnpm prints Ignored build scripts (for example esbuild), run:

pnpm approve-builds

2. Run the dev server

pnpm dev

Quality Checks

Run locally with pnpm scripts:

pnpm lint
pnpm format:check
pnpm test:unit
pnpm typecheck
pnpm check

Focused unit test suites:

pnpm test:network
pnpm test:terminal
pnpm test:terminal:llm
pnpm test:terminal:settings
pnpm test tests/terminalKnowledge.test.ts tests/terminalRouter.test.ts
pnpm test:content
pnpm test:device
pnpm test:schemas
pnpm test:api

test:api includes API helper tests, response contract tests, and route contract tests (failure and success paths).

Or use make shortcuts:

make lint
make test-unit
make test-network
make test-terminal
make test-terminal-llm
make test-terminal-settings
make test-content
make test-device
make test-schemas
make test-api
make typecheck
make check

3. Environment variables

Copy .env.example to .env and fill in:

# AI Terminal (server-owned defaults)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
# Optional (used for request headers / OpenRouter rankings)
# PUBLIC_SITE_URL=https://your-domain.tld
# PUBLIC_SITE_NAME=DG-Labs OS

# Site
# PUBLIC_SITE_URL=https://your-domain.tld

# Supabase (server-only; do NOT expose in PUBLIC_ vars)
SUPABASE_URL=https://YOUR-PROJECT.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Security notes:

• .env* files are gitignored (except .env.example).
• If an env file was committed in the past, remove it from git tracking before push:

git rm --cached .env.local .env.production .env

Configuration

Edit the config files in src/config/:

• personal.ts - name, role, focus
• social.ts - GitHub, LinkedIn
• contact.ts - email, phone, Calendly
• education.ts, experience.ts, skills.ts
• projects.ts + src/config/projects/*.json
• apps.ts - resume asset links (pdf, docx, markdown)
• site.ts - SEO + theme colors

Resume Module

Resume is now served from local static assets instead of Google Drive:

• /cv/Dessi_Georgieva_CV.pdf
• /cv/Dessi_Georgieva_CV.docx
• /cv/Dessi_Georgieva_CV.md

Canonical source markdown lives at:

• src/data/resume/cv.md

Sync canonical markdown into downloadable public assets:

pnpm resume:sync

Generate PDF + DOCX + Markdown from the canonical source using Pandoc:

pnpm resume:build

Requirements for resume:build:

• pandoc installed
• one PDF engine installed:
  • xelatex or pdflatex or lualatex or tectonic
  • or wkhtmltopdf
  • or weasyprint

If only markdown sync is needed (no PDF/DOCX regeneration), use pnpm resume:sync.

Deployment

This project runs with Astro SSR (API routes). Deploy anywhere that supports a Node runtime.

For Vercel deployment specifics, use:

• docs/VERCEL_DEPLOYMENT_RUNBOOK.md

Release Checklist

Use this quick path before and after each merge to main.

1. Pre-merge local checks

pnpm install --frozen-lockfile
pnpm check
pnpm deploy:preflight
pnpm build:vercel

2. Secret hygiene

git ls-files | rg -n "^\\.env"

Expected: only .env.example.

3. Post-deploy smoke checks

• Open /desktop
• Open /apps/network and toggle List/Graph
• Open /apps/terminal, run help and one ask ...
• Check provider status endpoint: /api/llm/health?probe=0

4. Full operational guide

• docs/VERCEL_DEPLOYMENT_RUNBOOK.md

License

MIT