signaldesk-setup

name	signaldesk-setup
description	Set up and run the SignalDesk Convex starter from a fresh clone. Use when an attendee wants to fork, install, run locally, add their OpenAI key, or deploy SignalDesk to Convex static hosting.

Set up SignalDesk

SignalDesk is a realtime agentic lead board built on Convex for the AI Growth Hackathon by Orange Slice. Use this skill to take an attendee from a fresh clone to a running app, then to a live deploy. Works in Cursor, Claude Code, Codex, or a plain terminal.

What this app is

• Frontend: React, Vite, TypeScript.
• Backend: Convex queries, mutations, scheduler, and a Node action for OpenAI.
• Hosting: the @convex-dev/static-hosting component serves the built app from Convex. No other host needed.
• AI: bring your own OpenAI key, set with the Convex CLI. Without a key the app runs in demo mode with deterministic mock enrichment, so it works immediately.
• Auth: off by default. To add it, use the signaldesk-enable-auth skill or docs/AUTH.md.

Prerequisites

• Node 18 or higher and npm.
• A Convex account for deploys (npx convex login). Local dev can run anonymous.

Steps

1. Install dependencies:

   npm install
   

2. Start the Convex backend. On first run this provisions a deployment and writes VITE_CONVEX_URL into .env.local:

   npx convex dev
   

   Keep this running in its own terminal. For a cloud agent or sandbox without login, use anonymous mode:

   CONVEX_AGENT_MODE=anonymous npx convex dev --once
   

3. In a second terminal, start the frontend:

   npm run dev
   

   Open the printed local URL. Add a company on the board. Open a second tab and watch it update live. That is Convex realtime.

4. Optional: switch on real AI by setting your OpenAI key on the backend. This is the secure path. The key never touches the browser or git.

   npx convex env set OPENAI_API_KEY sk-your-key
   

   Then open the Settings tab in the app and click Check key status.

Deploy to Convex static hosting

One command builds the frontend with the correct production URL, deploys the backend, and uploads the static files:

npx convex login   # once
npm run deploy

The app goes live at your https://<deployment>.convex.site URL. For production AI, also set the key on prod:

npx convex env set OPENAI_API_KEY sk-your-key --prod

Where things live

• convex/leads.ts board queries, add and remove mutations, internal helpers.
• convex/enrich.ts the Node action that calls OpenAI or the mock.
• convex/activity.ts the live activity feed query.
• convex/staticHosting.ts and convex/http.ts static hosting wiring.
• src/ the React UI.
• docs/SETUP.md, docs/AUTH.md, design.md, README.md the docs.

Rules to follow when editing

• Keep argument and return validators on every Convex function.
• Schedule only internal functions.
• Use indexes, not filters, for data access.
• Never use Date.now() inside a query.
• Run npm run typecheck and npm run lint before calling it done.

References

• Convex docs: https://docs.convex.dev
• Convex AI rules: https://docs.convex.dev/ai/overview
• Static hosting component: https://www.convex.dev/components/static-hosting
• Orange Slice CLI agent: https://www.orangeslice.ai/agents and npx orangeslice@latest