/create-dashboard

name: create-dashboard
description: >
  Create a custom web dashboard (React + Vite + Express) inside your sandbox to visualize
  the agent's Turso database. The dashboard is served on port 3847 and the user sees it
  live in the "App" tab in Gooseworks. Use when the user asks for a dashboard,
  visualization, chart, metric view, or any custom UI powered by their agent's data.
tags: [content, design]

You are helping the user build a custom dashboard from the Gooseworks dashboard template. The app must run on port 3847 from a single Express process that serves both the API routes and the built React UI so it appears in the Gooseworks App tab.

Where the source lives (read this first)

The **runnable project folder is `/home/user/dashboard`**. That is the ONLY directory you should `cd` into for any npm / build / server command. Most files inside it are symlinks pointing back into the canonical source under the agent's workspace folder (the file you'd see at the canonical path is the same file you'd see through the symlink — it's one file, two paths). The runnable project folder also holds two real local directories that must NOT be on the workspace mount: `node_modules` (dependencies) and `dist` (built bundle).

/home/user/dashboard/                    ← cd here for everything
  package.json, package-lock.json,
  server.js, src/, vite.config.ts, …    (symlinks → workspace canonical source)
  node_modules/, dist/, .vite/, .cache/  (real local dirs — never on workspace)

What this means for you:

• **Always `cd /home/user/dashboard` before running npm / vite / node /

any shell command.** Tools resolve modules from the `node_modules` next to the cwd. Running them from the canonical source path under the workspace folder will install `node_modules` directly into the workspace mount — that puts tens of thousands of files on s3fs, hits its filesystem-semantics limits (npm gets `ENOTEMPTY` on package renames), and the install will spin forever.

• **Edits to source files at `/home/user/dashboard/src/...` (or any

other symlinked path) auto-persist** to the workspace mount through the symlink. There is no separate sync step. You may also edit the canonical path directly; both paths land in the same file.

• **Never run `npm install`, `npm ci`, `vite build`, or `node server.js`

from inside the workspace canonical source folder.** Those commands will pollute the workspace with `node_modules` / `dist` / build caches and break future restores.

Non-negotiable constraints

1. Always use the template workflow (React + Vite + Tailwind + Express). Do not rebuild this in another framework. 2. The runnable project folder is `/home/user/dashboard`. Use that literal path when telling the user where you cd or which file you edited; do not invent shell-variable strings. 3. Always `cd /home/user/dashboard` before running npm / vite / node. Edits to symlinked source files inside it propagate to persistent storage automatically; no separate sync step is needed. 4. `node_modules` and `dist` are LOCAL only. Never copy them into the workspace folder. 5. Use one runtime port (3847) and one server process. No separate frontend dev server.

State handling

Before editing, inspect:

• whether the runnable project folder's `package.json` is a symlink (it should be — this confirms the symlink layout is in place)
• whether the local `node_modules` folder inside the runnable project folder is populated
• whether port 3847 has a healthy server

Then follow this decision flow:

• All three OK: move to customization.
• Symlinks missing or `node_modules` empty: ask the platform to re-run the start flow (it will set up symlinks + npm install + build + launch).
• `package.json` is a real file (not a symlink): the sandbox is in a legacy state — ask the platform to re-run install/start so the symlink layout gets put in place.

The platform's start/install orchestrator handles symlink setup, dependency install, build, and launch automatically. You don't run those steps by hand unless something is broken.

Discovery and planning

Before coding: 1. Clarify what the user wants to visualize if unclear. 2. **Always check the agent's database first.** If the agent has a Turso database with relevant tables, the dashboard must read from it. Never invent placeholder rows, mock arrays, or hard-coded sample data when real data is available. Use mock data only when the user explicitly asks for a demo with no DB, and clearly label it as mock in the UI. 3. Inspect the database schema using the database query tool:

• list tables
• inspect columns for relevant tables
• run a small sample query to confirm shape and row counts before wiring a chart
• if the relevant tables are missing, follow the **Empty-database handling** section below — propose a schema and create the tables rather than defaulting to mock data

4. If the request is vague, confirm a one-sentence implementation plan.

Data source preference

Order of preference for every panel, chart, and table: 1. Live query against the agent's database via the runQuery helper or a read-only API route. 2. A user-provided file (CSV, JSON) already in the workspace. 3. Mock data — only as a last resort, with explicit user permission, and labelled as such on screen.

Empty-database handling (important)

The user is often non-technical and will not know how to create a schema themselves. **Do not fall back to "sample data" the moment a table is missing.** Instead, when the DB is reachable but the tables needed for the requested dashboard do not exist:

1. Confirm which tables exist by listing them through the database tool. 2. Tell the user in plain language that the table(s) the dashboard needs are not there yet, and propose a small, sensible schema based on what they asked for (e.g., for a "revenue dashboard": a `deals` table with `id`, `name`, `amount`, `stage`, `closed_at`, plus a `revenue_daily` rollup if useful). Keep the schema minim