signaldesk-setup

# 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: ```bash npm install ``` 2. Start the Convex backend. On first run this provisions a deployment and writes `VITE_CONVEX_URL` into `.env.local`: ```bash npx convex dev ``` Keep this running in its own terminal. For a cloud agent or sandbox without login, use anonymous mode: ```bash CONVEX_AGENT_MODE=anonymous npx convex dev --once ``` 3. In a second terminal, start the frontend: ```bash 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. ```bash 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: ```bash 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: ```bash 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`