> For the complete documentation index, see [llms.txt](https://cuesoft.gitbook.io/consoless/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cuesoft.gitbook.io/consoless/setup.md).

# Setup

## Prerequisites

* **Node.js** 24 (see `web/.nvmrc`)
* **npm**

Only the web app exists today. It needs no backend: in TEST\_MODE it talks to an in-app mock server and signs you in as a local test user.

## Run the web app

```bash
git clone https://github.com/cuesoftinc/consoless.git
cd consoless/web
npm ci
NEXT_PUBLIC_TEST_MODE=true npm run dev
```

Open `http://localhost:3000` and choose Sign in. "Continue with Google" signs you in without contacting Google.

| Route                    | What it is                                                   |
| ------------------------ | ------------------------------------------------------------ |
| `/`                      | The landing page                                             |
| `/signin`                | Sign-in (Google only)                                        |
| `/arcade`                | The Arcade: published games, open to everyone                |
| `/arcade/{slug}`         | A game's page: leaderboard, share, remix and report          |
| `/dashboard`             | My Games, behind the one-time 16-or-older check              |
| `/dashboard/studio/new`  | New game: a first prompt and a console style                 |
| `/dashboard/studio/{id}` | The Studio: chat, preview, code, versions, style and publish |
| `/dashboard/settings`    | Settings: Profile, Appearance, Data and privacy              |
| `/dev/components`        | The component gallery (dev and TEST\_MODE builds only)       |
| `/api/mock/v1/*`         | The mock server, mirroring the API path for path             |

## Configuration

Never commit secrets. Configuration comes from environment variables; `web/.env.example` lists them.

| Variable                | Used by              | Description                                                                                                                                                |
| ----------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_TEST_MODE` | web                  | `true` points the API client at the mock server and uses the test-mode sign-in. The hosted site sets it in `web/apphosting.yaml` until `api/common` exists |
| `PW_PORT`               | web end-to-end tests | Port for the Playwright server. Defaults to 3150                                                                                                           |

## Checks

Run these from `web/` before opening a pull request. CI runs the same set.

```bash
npm run lint         # prettier, eslint and the layer boundary check
npm run typecheck
npm test             # unit and integration tests (Vitest)
npm run build
npm run test:e2e     # Playwright, against the TEST_MODE app
```

`POST /api/mock/v1/testing/reset` re-seeds the mock server. The mock keeps state per signed-in user, so journeys that change data do not affect each other: send `{"user_id": "usr_..."}` to re-seed one user. In TEST\_MODE the Google button signs in `usr_playerone`, a returning creator with sample games. To sign in as someone else, set `localStorage["consoless.test-user"]` to a user id before clicking it; ids beginning `usr_new` are first-time users with no games who have not answered the age check.

The mock builds every prompt into a version after a few seconds. Two prompts drive the other outcomes: one containing `[fail]` fails its checks, and one containing `[refuse]` is refused. A code edit fails its check when its braces do not balance.

## Docker

```bash
docker compose up --build -d   # or: make up
```

This builds `web/Dockerfile` in TEST\_MODE and serves the app on port 3000. The compose file holds only the web app today; the engine and the services join it as they are built.

## Theme

Light is the default theme. The preference (light, dark or system) is stored in the browser at `consoless.theme`.

## Docs site

The docs in this folder are published with GitBook's Git Sync. Two files at the repository root configure it: `gitbook-docs.yaml` names the site and maps its space to the repository, and `.gitbook.yaml` points that space at `docs/`, with `overview.md` as the first page and `SUMMARY.md` as the navigation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cuesoft.gitbook.io/consoless/setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.