QUICKSTART.md

Quick Start Guide

Get DriveCore running in under 5 minutes.

---

1. Prerequisites

• Bun ≥ 1.0 — install via curl -fsSL https://bun.sh/install | bash (or use npm/pnpm)
• Node.js ≥ 20 (only needed if you don't use Bun)
• A Lovable account with this project linked to your GitHub repo

---

2. Get the code

git clone https://github.com/<your-org>/guardian-owl-56.git
cd guardian-owl-56
bun install

---

3. Environment variables

The .env file is auto-generated and managed by Lovable Cloud — don't edit it.

It already contains:

VITE_SUPABASE_URL=...
VITE_SUPABASE_PUBLISHABLE_KEY=...
VITE_SUPABASE_PROJECT_ID=...

Server-side secrets (set via Lovable Cloud → Secrets, never commit them):

Secret	Required for
LOVABLE_API_KEY	AI features (auto-provided by Lovable)
BRANCH_DEBUG_TOKEN	CLI / VS Code Branch Debug endpoint

---

4. Run the dev server

bun run dev

Open http://localhost:5173 → you'll land on the marketing page.

Click Sign In → create an account → you're routed into /dashboard.

---

5. Try the core flows

a. Branch Debug (no setup needed)

1. Go to Dashboard → Branch Debug.
2. Paste any git diff and a one-sentence failure description.
3. Click Analyze — you'll get ranked suspects with file/line + sanitization audit.

b. Forensic analysis

1. Go to Dashboard → Forensic.
2. Submit a public URL or upload a file.
3. View the agent pipeline output and severity scoring.

c. Incidents

1. Go to Dashboard → Incidents.
2. Create an incident, run AI analysis, resolve.

---

6. Build for production

bun run build      # bundles for Cloudflare Workers
bun run preview    # smoke-test the build locally

To deploy: just push to your default branch — Lovable Cloud handles the deploy. Or click Publish in the Lovable editor.

---

7. Use Branch Debug from your terminal

export BRANCH_DEBUG_TOKEN="<from Lovable Cloud secrets>"

git diff main...HEAD | node cli/eventdash-debug.mjs \
  --failure "tests pass locally but fail on CI for EU users"

The CLI POSTs to:

https://project--bff39f15-1e2d-4d34-8f4b-7070bac6dbae.lovable.app/api/public/branch-debug

with Authorization: Bearer $BRANCH_DEBUG_TOKEN.

---

8. Where to look next

I want to…	Open
Add a new page	src/routes/<name>.tsx
Add backend logic	src/server/<name>.functions.ts (use requireSupabaseAuth)
Change colors / theme	src/styles.css (semantic tokens only)
Modify the database	Use the Lovable Cloud migration tool — never edit src/integrations/supabase/types.ts
Add a secret / API key	Lovable Cloud → Secrets
Read security guarantees	README.md

---

Troubleshooting

Symptom	Fix
LOVABLE_API_KEY not configured	Open Lovable Cloud → confirm the secret exists; restart dev server
401 from /api/public/branch-debug	Set BRANCH_DEBUG_TOKEN env var to match the secret in Lovable Cloud
Blank dashboard after login	Hard refresh; check browser console — likely a stale auth session
Build fails with "Failed to resolve import"	A file/package was referenced before being created/installed — re-run bun install
Migration fails with ALTER DATABASE	Remove that line — not allowed on Lovable Cloud

---

Need more detail? See the full README. Happy debugging 🦉