---
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 minimal — only the columns the requested charts actually need.
3. Get a one-line confirmation from the user, then create the tables via the database tool. Use sensible types and primary keys. Add helpful indexes for the columns the dashboard will filter or group by.
4. Offer to seed a small set of realistic example rows so the charts have something to render immediately. Seed only if the user agrees, and tell them clearly that these rows are starter examples they can delete or replace.
5. Wire the dashboard to the newly created tables. Do **not** also keep a mock-data fallback in the code — once the table exists, the empty state in the UI is enough.

If the user declines schema creation, render a calm empty state ("no data yet — connect a table named X with columns A, B, C to see this chart") in stone tones rather than filling the chart with fake numbers.

Never create or alter tables that already contain user data without an explicit instruction. Never drop tables. All table creation must be additive.

## Implementation guidance

Template structure to use:
- A server entry module for API routes and static serving.
- The root App component for route registration.
- A **layouts folder** under src/components/layouts/ that holds six shell components — pick the one that matches what the user is building (see "Choosing a layout" below).
- A pages folder for page implementations.
- A small API helper module exporting a runQuery function for data access from pages.

For each new page:
1. Add a page component to the pages folder.
2. Pull data using the runQuery helper, or a dedicated read-only API route when SQL becomes complex.
3. Add route wiring in the root App component.
4. Add a navigation entry in whichever layout shell the App component is wrapped in (sidebar nav, top nav, or tab bar — depending on the chosen layout).

Keep all dashboard endpoints read-only.

### Choosing a layout

Six layout shells live in `src/components/layouts/`. The default `App.tsx`
wraps routes in `SidebarLayout`. Swap the import + wrapper in `App.tsx` to
the shell that matches what the user is asking for:

| Shell | Use when the user asks for… |
| --- | --- |
| `SidebarLayout` (default) | a multi-section app with several pages (analytics, admin, multi-page tool) |
| `TopNavLayout` | a single-purpose dashboard, marketing-style report, or something that wants full-width content |
| `TopNavTabsLayout` | a Stripe-Dashboard-style sectioned view where tabs slice the same workspace |
| `SplitPaneLayout` | inbox / CRM / chat / mail-style apps — list on the left, detail on the right. Pass `list` and `detail` as separate props |
| `CanvasLayout` | a one-page report, embed, or screen with no chrome at all |
| `CenteredLayout` | login forms, onboarding screens, single-action surfaces |

Rules:
- **Pick exactly one** shell per dashboard. Do not mix two shells in App.tsx.
- Before swapping the shell, confirm the choice with the user in one sentence ("I'll build this as a split-pane inbox — list on the left, message on the right. OK?").
- After swapping the shell, edit the nav entries inside that shell file to match the routes you wire up.
- All shells share the same stone palette, typography, and spacing — do not introduce new colors or fonts when switching shells.
- `SplitPaneLayout` takes `list` + `detail` props instead of `children`. App.tsx should render the list pane (route-agnostic) and the detail pane (typically a `<Routes>`) as those two props.

## Visual style rules

Design inspiration: aim for the calm, content-first feel of Linear, Vercel, Stripe, and Notion analytics dashboards. The dashboard should look like a quiet reporting surface, not a colourful BI tool. Density is good; chart-junk is not.

Concrete rules:
- Use the stone color palette only — stone-tinted text, borders, and backgrounds. No blues, greens, purples, or rainbow palettes.
- Prefer compact typography (extra-small or small text sizes) with a normal font weight. Avoid bold headlines except for the page title.
- Keep borders minimal (single hairline in a light stone tone) and avoid heavy shadows or rounded "card" stacks. Flat surfaces only.
- For Recharts lines, bars, and grids, stay within the stone color family. Use opacity to differentiate series instead of hue. Single-series charts should be a single mid-stone tone.
- Layout: pick a shell from `src/components/layouts/` (see "Choosing a layout" above) instead of inventing a new chrome. Within whichever shell you pick, keep the main content column generous on whitespace, KPIs as a row of small stat blocks at the top, charts and tables stacked below.
- Empty states, loading states, and error states must follow the same stone palette and typography — no spinners with brand colours, no red error toasts.

When in doubt, look at the existing pages in the template and match their density, spacing, and tone before adding anything new.

## Build, run, and verify

The dashboard does **not** hot-reload on file changes. After editing
source files under `/home/user/dashboard/src/...`, run `npm run build`
from `/home/user/dashboard`. You do **not** need to restart the server
for `src/` edits — the running Express server uses
`express.static(dist/public)` and reads files from disk on every
request, so the next iframe refresh picks up the freshly-built bundle
automatically (Vite emits new hashed asset filenames; the new
`index.html` points to them).

Default flow after a `src/` edit:
1. Run `npm run build` from `/home/user/dashboard`.
2. Tell the user the update is live and to refresh the App tab. Done.

**Do not stop, kill, or restart the dashboard server as part of the
normal edit loop.** Doing so wastes time and creates a failure mode:
the agent backgrounds `node server.js`, then polls the background task
waiting for it to "complete" — but a healthy server is a long-lived
process, so the poll loop never resolves and the chat appears frozen.

### When a restart IS warranted

Only restart the server when one of these is true:

- You edited `server.js` itself (new API route, new middleware, anything
  that changes server behavior — Express won't pick those up without a
  process restart).
- The server isn't running on 3847. The platform's start flow is the
  right tool for this — ask it to start; do not hand-roll a launch.
- The user reports a visible problem with the dashboard (blank App tab,
  stale UI even after refresh, an error they can see) and a restart is
  a plausible fix. In that case: stop the old process using the
  port-scoped cleanup pattern (never broad pkill inside the sandbox),
  launch the new one, then verify health via the `/api/health` endpoint.

If you do launch `node server.js` yourself, fire-and-forget it
(redirect output to a log file, return immediately) and verify via
the `/api/health` endpoint. Never poll a background-task output waiting
for the server process to exit — it won't.

### Verifying after work that warranted a restart

Hit the health endpoint:
- ok=true with db=true: dashboard is live.
- db=false: inform the user that agent DB credentials/config are missing and stop further DB-dependent work.

## Troubleshooting

If the user reports a problem with the dashboard, walk through this list in order before making code changes. Most "the dashboard is broken" reports are environmental, not bugs in the user's pages.

1. **App tab is blank or shows a connection error.** Check whether the server is actually running on port 3847 (hit the `/api/health` endpoint). If not, ask the platform to re-run the start flow.
2. **Health endpoint returns ok=false or db=false.** The agent's database credentials are missing or invalid. Tell the user this directly; do not try to silently swap in mock data.
3. **Page renders but charts/tables are empty.** Run the underlying query through the database tool to confirm whether the table actually has rows. If the table is missing entirely, follow the Empty-database handling section — offer to create the schema; do not silently swap to mock data. If the table exists but is empty, render an empty state. If rows exist, check the runQuery call and column names.
4. **"Module not found" or import errors after editing.** A new package was used without being added to `package.json`. Add it. Then change directory into `/home/user/dashboard`. Then run `npm install`. Then rebuild. **Never run `npm install` from anywhere under the workspace folder** — that installs `node_modules` into the workspace mount, which hits s3fs filesystem-semantics limits and spins forever.
5. **Changes do not appear in the App tab.** The build wasn't run after the edit, or the user hasn't refreshed yet. Run `npm run build` from `/home/user/dashboard` and ask the user to refresh — Express serves the new bundle from disk, so no server restart is needed for `src/` edits. Only restart the server if a refresh still shows stale output.
6. **Stale UI after a long session.** The build output diverged from source. Remove the `dist` folder inside the runnable project folder and rebuild.
7. **The runnable project folder's `package.json` is a real file (not a symlink).** The sandbox is in a legacy / pre-symlink state. Ask the platform to re-run the start flow — it will rewire the symlinks and rebuild.
8. **Sandbox restarted and the dashboard isn't running.** Just ask the platform to start it. The source persists in S3 via symlinks, so there's nothing for you to restore.

If none of the above resolves it, read the server logs, summarize the actual error to the user in plain language, and propose the smallest fix.

## Completion message

End with a direct status message that the dashboard is live in the App tab and ready
for further edits.

## Iteration loop

For every follow-up tweak (this loop is the agent's job, not the user's):
1. Edit relevant files at `/home/user/dashboard/...`. Symlinks persist edits to the workspace automatically; no sync step.
2. Run `npm run build` from `/home/user/dashboard`. Do **not** restart the server — Express serves the new `dist/` automatically on the next request.
3. Tell the user the update is done and ask them to refresh the App tab.

Restart the server only in the cases listed under "When a restart IS warranted" above (`server.js` changed, server not running, or the user reports a visible problem).