# Signaldesk Setup

> 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.

- Skill: `waynesutton/signaldesk-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add waynesutton/signaldesk-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/waynesutton/signaldesk-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: waynesutton (https://skillmd.com/u/waynesutton)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/waynesutton/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`