01 — set it up

Quickstart

Boot the cancri terminal locally in one shot, against an in-browser mock feed. No Node on your machine, no Firebase project, no secrets. The only host requirement is Docker — everything else runs in a node:26 container.

One-shot quickstart

Clone the repo and run the quickstart script. First run pulls dependencies and generates design tokens (the slow one); after that it's a few seconds.

git clone https://github.com/t11z/cancri.git
cd cancri
scripts/quickstart.sh        # → http://localhost:5173

That's it. The script checks Docker is present and running, then boots the terminal. When you see Vite's banner, open localhost:5173.

Prerequisites

Docker

Docker Desktop (macOS / Windows) or Docker Engine (Linux), running. This is the only host requirement.

git

To clone the repository.

Node

not required — it lives inside the container.

Firebase

not required for local dev — the mock feed needs no backend.

On Windows, run the script from a shell that has Docker on its PATH (e.g. WSL). Override the image or port with CANCRI_NODE_IMAGE / CANCRI_DEV_PORT if you need to.

What you'll see

The terminal boots through its sequence and lands on the auth gate. Because there's no backend in local dev, the onboarding and dashboard are driven by a mock feed and the dev-only review bar.

[ok]  cancri // live-portfolio-terminal — online
[net] establishing socket → primary feed — handshake
[net] subscribing instruments · L1 quotes
[llm] gemini intake channel ready
[ok]  freshness monitor armed · live/delayed
[ok]  terminal ready ✓
mounting workspace… ▮

The review bar

The local dev build ships a dev-only // review bar that jumps between every screen and dashboard state — so you can inspect the whole terminal without wiring up a backend. It never ships to users.

Everyday commands

All three scripts are containerised — no host Node. They share a cached pnpm store volume.

Full Firebase emulator suite

The mock feed is enough to explore the UI. To exercise the real data paths — auth, per-user persistence, the security rules, Gemini normalisation, and the RTDB tick bus — run the Firebase Emulator Suite. It needs a JDK (the Firestore / Database emulators are Java); the containerised flow handles that for you.

# security rules + per-user persistence + tick-bus, against the emulators
firebase emulators:exec --only auth,firestore,database --project demo-cancri \
  "pnpm --filter @cancri/rules-tests exec vitest run &&
   pnpm --filter @cancri/web exec vitest run src/persistence.test.ts src/rtdb-source.test.ts"

This is exactly what CI's rules job runs. The full emulator + going-live runway (Vertex, Cloud Run, WIF) is documented under Deploy and SETUP.md.

Troubleshooting

Next steps

• Usage — walk the onboarding flow and read the dashboard.
• Contributing — the dev loop, tests, and the smADR ritual.
• Deploy — ship it to Firebase when you're ready.