---
name: bigstack-arda-setup
version: 0.1.0
description: |
  Set up and run the arda webapp from the Bigscreen cloud repo. Checks
  prerequisites without installing anything (reports gaps and tells the
  user how to fix them). Once prereqs are satisfied, builds the frontend,
  starts arda-server and the webpack watcher, and opens arda in a browser.
  Never starts the rest of the cloud services.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - AskUserQuestion
---
<!-- Auto-generated from SKILL.md.tmpl by bigstack. DO NOT EDIT. -->
<!-- Regenerate: npm run gen:skill-docs -->

<!-- bigstack v0.1.0 | skill: bigstack-arda-setup -->

> **bigstack v0.1.0** — skills for Bigscreen development.

Before starting, run this setup block silently:

```bash
# Session context
BIGSTACK_VERSION="0.1.0"
BIGSTACK_DIR="C:/Users/GGPC/Documents/Github/bigstack"
REPO_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "bigstack v$BIGSTACK_VERSION | repo: $REPO_NAME | branch: $BRANCH"
```

**Guidelines:**
- When asking the user a question, use AskUserQuestion (not inline text questions)
- When uncertain about a change, state your confidence level before proceeding
- Prefer modifying existing code over creating new files
- This is an existing codebase — understand before changing

# /bigstack-arda-setup — Arda Webapp Setup + Run

Gets the arda webapp from a "fresh-cloned cloud repo" state to "running
in my browser", with two hard rules:

1. **Never auto-install prerequisites.** Node, Yarn, webpack, and the
   `.env` file must be provided by the user. The skill inspects and
   instructs; it doesn't touch the toolchain.
2. **Only arda.** Don't start admin-api, api, cloud-api, ws-server, or any
   other cloud service. If the user wants the whole stack, point them at
   `/bigstack-cloud-setup`.

## Cloud repo detection

The skill never assumes a hardcoded path. It finds the cloud repo by:

1. `CLOUD_DIR` env var if set (explicit override)
2. Walking up from the **current working directory** looking for a
   `package.json` with `"name": "bigscreen"` plus a `webapps/arda`
   directory
3. Checking `$(pwd)/cloud` subdirectory
4. If none match, the skill asks the user whether to clone fresh into
   `./cloud` or provide a path to an existing repo

This means the skill works from inside the cloud repo, from a workspace
that already contains `./cloud`, or from a fresh empty folder (where it
offers to clone for you).

```mermaid
flowchart TD
  Start([/bigstack-arda-setup/]) --> Detect{Detect cloud repo<br/>via check-arda-prerequisites.sh}
  Detect -->|exit 0 or 1<br/>repo found| Branch[Select branch<br/>latest dev-* default<br/>or latest main-*]
  Detect -->|exit 2<br/>no repo| Ask{Ask user}
  Ask -->|Clone fresh| Clone[git clone into ./cloud<br/>fail hard if clone errors]
  Ask -->|Existing path| GetPath[User provides full path]
  Clone --> Branch
  GetPath --> Branch
  Branch --> Sync[git checkout + pull<br/>yarn install both roots]
  Sync --> Check[Evaluate prereq results]
  Check --> Gate{All green?}
  Gate -->|No| Instruct[Print missing items + fix commands<br/>STOP — wait for user]
  Instruct --> Recheck[User fixes, asks to re-run]
  Recheck --> Detect
  Gate -->|Yes| Launch[Launch watcher + server<br/>both backgrounded — MUST]
  Launch --> Poll[Poll port 3010<br/>up to 90s]
  Poll --> Open[Open http://localhost:3010]
  Open --> Done([arda running])
```

## Workflow

### Step 0: Resolve CLOUD_DIR

Run the check script — it both detects the repo and reports prereqs. Its
exit codes are meaningful:

- **exit 0** — everything green, skip to Step 3
- **exit 1+** but cloud repo was found — go to Step 2 (report gaps)
- **exit 2** — cloud repo was NOT found, run Step 0a (interactive recovery)

Capture the `CLOUD_DIR=<path>` line the script prints — that's the path
all subsequent commands use.

#### Step 0a: No cloud repo found — ask the user

Tell the user (in chat) what the skill is about to do before asking —
they should understand they're about to either clone a ~500MB git repo
or hand over a path:

> I couldn't find the Bigscreen cloud repo on this machine. It lives at
> `github.com/BigscreenVR/cloud` and isn't public, so you'll need git
> access to the BigscreenVR org. I can either:
>   1. Clone it fresh into `./cloud` in the current folder, or
>   2. Use an existing clone if you already have one — just tell me the path.

**Use `AskUserQuestion`** with two options:

1. **"Clone cloud repo into ./cloud"** — skill runs `git clone` from cwd.
2. **"I'll specify an existing path"** — skill replies in chat asking
   for the full absolute path in the next turn (free-form answer, no
   AskUserQuestion).

##### If the user picks "Clone":

**Pre-flight**: refuse to clone on top of an existing `./cloud`
directory. If it already exists but wasn't recognised as the cloud repo,
something unexpected is there — don't overwrite it:

```bash
if [ -e "$(pwd)/cloud" ]; then
  echo "ERROR: ./cloud already exists but wasn't recognised as the cloud repo."
  echo "       Either remove/rename it, or pick the 'specify an existing path' option."
  exit 1
fi
```

**Narrate what's about to happen** so the user knows why it takes a
minute or two:

> Cloning BigscreenVR/cloud (~500MB) into ./cloud — this can take 1–3
> minutes depending on your connection. If git prompts for auth, your
> GitHub credentials aren't set up; I'll have to stop and hand it back
> to you to configure.

Then clone:

```bash
git clone https://github.com/BigscreenVR/cloud.git cloud
```

**If the clone fails, stop.** The skill assumes the user's local
git/GitHub access is already configured (SSH key, `gh auth login`, or
cached HTTPS credentials for github.com). If the error is
auth-related (`fatal: Authentication failed`, `Permission denied
(publickey)`), tell the user exactly that and point at
`gh auth login` as the usual fix — but don't attempt to configure
credentials from inside the skill.

Once the clone succeeds, pin `CLOUD_DIR` for subsequent steps:

```bash
export CLOUD_DIR="$(pwd)/cloud"
```

Then jump to Step 0b (branch selection on the fresh clone).

##### If the user picks "specify an existing path":

Ask in chat (free-form — AskUserQuestion is multiple-choice, so this
must be a normal chat turn):

> Please paste the full absolute path to the cloud repo on this machine.

When they reply, validate it's actually a cloud repo checkout — a wrong
path produces confusing failures later:

```bash
# Replace <user-path> with what they sent
CLOUD_DIR="<user-path>"
if [ ! -d "$CLOUD_DIR/.git" ]; then
  echo "ERROR: $CLOUD_DIR is not a git repo"
elif [ ! -d "$CLOUD_DIR/webapps/arda" ]; then
  echo "ERROR: $CLOUD_DIR has no webapps/arda — not the cloud repo"
else
  export CLOUD_DIR
  # Proceed to Step 0b
fi
```

If validation fails, tell them why and ask again.

### Step 0b: Select the branch to run from

**Context to share with the user** before running any git commands:

> The cloud repo uses a branch convention where `dev-*` branches are
> active development (what the team is currently building) and `main-*`
> branches are stable release cuts. Arda runs against whichever branch
> you have checked out, so picking the right one matters. I'll show you
> the most recent of each and default to the latest `dev-*`.

Walk through git operations in this order, narrating each one so the
user can follow along:

#### 1. Fetch the latest refs from origin

```bash
cd "$CLOUD_DIR" && git fetch origin --prune
```

**Tell the user**: "Fetching latest branch list from origin
(non-destructive — doesn't touch your working tree). `--prune` drops refs
for branches that have been deleted on the remote."

#### 2. Refuse to clobber uncommitted work

Branch switching can overwrite modified files. Before even considering a
checkout, bail out if the working tree has uncommitted changes — losing
WIP is never worth a faster setup:

```bash
DIRTY="$(git -C "$CLOUD_DIR" status --porcelain)"
if [ -n "$DIRTY" ]; then
  echo "ERROR: uncommitted changes in $CLOUD_DIR — commit or stash them first."
  echo "$DIRTY"
  exit 1
fi
```

**Tell the user if dirty**: "Your working tree has uncommitted changes
(shown above). I won't switch branches over your work. Commit or stash,
then re-run the skill." Do not offer to auto-stash — that hides intent.

#### 3. List recent `dev-*` and `main-*` branches

```bash
git -C "$CLOUD_DIR" for-each-ref --sort=-committerdate \
  --format='%(refname:short) %(committerdate:short)' \
  refs/remotes/origin/ \
  | grep -E '^origin/(dev-|main-) ' \
  | head -10
```

Show this list to the user as-is so they can see what's recent. Identify:
- `LATEST_DEV` — topmost `dev-*` branch from the list
- `LATEST_MAIN` — topmost `main-*` branch from the list

If the list is empty (no `dev-*`/`main-*` branches exist), tell the user
the fetch didn't surface any and hand back — they may need to check the
remote config or pick a branch by hand.

#### 4. Ask which branch to use

**Use `AskUserQuestion`** with these options, default = `LATEST_DEV`:

1. `<LATEST_DEV>` — latest development branch (**default**)
2. `<LATEST_MAIN>` — latest stable release branch
3. "Keep current branch" — skip checkout entirely (use whatever's
   already checked out; useful if the user is mid-feature on their own
   branch)
4. "Other" — user will name a different branch in the next chat turn

#### 5. Check out and fast-forward

Skip this block if they picked "Keep current branch":

```bash
cd "$CLOUD_DIR" && git checkout "<branch>"
cd "$CLOUD_DIR" && git pull --ff-only origin "<branch>"
```

**Tell the user**: "Checking out `<branch>` and fast-forwarding to
origin. `--ff-only` means if local history has diverged from origin,
the pull will refuse rather than create a silent merge commit — better
to stop and let you decide than rewrite history behind your back."

If `git pull --ff-only` fails with "not possible to fast-forward",
surface the error to the user and stop. The local branch has commits
that aren't on origin (or vice versa). Don't try to resolve it — that's
a human judgment call.

#### 6. Sync dependencies after the checkout

Branch switches frequently change `package.json` (added or removed deps,
version bumps). Run `yarn install` in **both** install roots so
`node_modules` matches the branch you just checked out:

```bash
cd "$CLOUD_DIR" && yarn install
cd "$CLOUD_DIR/webapps" && yarn install
```

**Tell the user**: "Running `yarn install` in the root and `webapps/`
to match the new branch. This is idempotent — fast (~5s) on a warm
repo, slower (2–10min) on a fresh clone or a significant branch jump.
After this, Step 1's prereq check will find `node_modules` already in
sync and skip Step 2a's auto-install."

### Step 1: Prerequisite check

```bash
bash "${CLAUDE_SKILL_DIR}/bin/check-arda-prerequisites.sh"
```

Pass `CLOUD_DIR` through the environment if Step 0a set it:

```bash
CLOUD_DIR="<resolved-path>" bash "${CLAUDE_SKILL_DIR}/bin/check-arda-prerequisites.sh"
```

The script exits with the number of issues found (0 = all good). It checks:

| Component | Why arda needs it |
|-----------|-------------------|
| Node.js v24+ | Runs arda-server and webpack |
| Yarn | Monorepo package manager |
| TypeScript tooling (`tsc`, `ts-node`) | arda-server TS sources |
| webpack (global) | Builds the arda frontend bundle |
| Cloud repo (auto-detected) | Source of arda |
| `node_modules` inside cloud repo | Dependencies must be installed |
| `webapps/arda/.env` | Runtime config + secrets for arda |

Arda is a frontend webapp that proxies to the backend API services — it
does **not** need Redis or PostgreSQL running on the local machine. The
prereq check deliberately skips them. For a full local stack, use
`/bigstack-cloud-setup`.

### Step 2: Gate — did everything pass?

```mermaid
stateDiagram-v2
  [*] --> Checking
  Checking --> AllGreen: exit 0
  Checking --> NodeModulesOnly: only node_modules missing
  Checking --> HasOtherGaps: system prereqs or .env missing
  NodeModulesOnly --> AutoInstall: run yarn install (no prompt)
  AutoInstall --> Checking: re-run check
  HasOtherGaps --> Reporting
  Reporting --> WaitingForUser: print fix commands
  WaitingForUser --> Checking: user says "re-run"
  AllGreen --> Running
  Running --> [*]
```

Two classes of gap:

- **Auto-fixable** — only `node_modules missing`. The skill handles it
  via Step 2a without asking.
- **User-fixable** — Node/Yarn/webpack/TypeScript/`.env`. The skill
  reports and stops. Never auto-install system toolchain pieces; never
  write `.env` files (they contain secrets).

For each user-fixable gap, quote the exact fix command from the script,
explain it in one sentence, and offer to re-run the check once the user
is ready.

| Gap | How the skill handles it |
|-----|--------------------------|
| Node missing / < v24 | Report: `volta install node@24` (install Volta first from https://volta.sh/) |
| Yarn missing | Report: `volta install yarn` |
| TypeScript missing | Report: `volta install typescript ts-node` |
| webpack not global | Report: `npm install --global webpack webpack-cli` |
| Cloud repo not found | Handled by Step 0a — skill asks clone vs. specify path |
| `root node_modules` missing | **Auto-install** via Step 2a |
| `webapps/node_modules` missing | **Auto-install** via Step 2a |
| `webapps/arda/.env` missing | Report: see Step 2b below |

#### Step 2a: Auto-install `node_modules`

The cloud repo has **two** install roots that both need deps:

1. `$CLOUD_DIR` (root) — yarn workspaces monorepo
2. `$CLOUD_DIR/webapps` — a separate package with its own `yarn.lock`
   that is NOT in the root workspaces list. Arda's
   `webapps/arda/webpack.config.js` requires modules from here
   (e.g. `copy-webpack-plugin`), so skipping this install causes the
   webpack build to fail with `Cannot find module 'copy-webpack-plugin'`.

If either `node_modules` directory is missing, the skill runs
`yarn install` in the corresponding directory automatically — no
AskUserQuestion, no confirmation. These are safe, reproducible,
project-scoped operations.

```bash
# Whichever is missing — run both if both are missing
cd "$CLOUD_DIR" && yarn install
cd "$CLOUD_DIR/webapps" && yarn install
```

**Do not** run `yarn run install-dev-deps` on a fresh clone — it fails
with "Couldn't find the node_modules state file" because Yarn 4 needs
`yarn install` to run first.

Expect 2–10 minutes per `yarn install` on a cold run. Tell the user
what's happening so they don't think the skill has stalled. If either
install fails, surface the error and stop.

After each install completes, re-run the prereq check (Step 1) and
evaluate the remaining gaps.

#### Step 2b: `.env` guidance

**IMPORTANT**: Do not read, display, or log `.env` contents. They contain
secrets.

Two standard ways to get one:

1. **Copy from a teammate** (fastest) — many dev envs share identical
   values.
2. **Generate from devops ServerEnvironmentBuilder**:

   ```bash
   cd <devops-repo>/ServerEnvironmentBuilder
   node app_v6.js \
     --default-config-file "<path>/server_keys/default_config.json" \
     --fleet-config-file "<path>/server_keys/dev/dev_config.json" \
     --allowed-apps-file "<path>/server_keys/dev/dev_allowed_apps.json" \
     --output-folder-path ./.out
   ```

   Then copy `.out/webapp_arda.env` to `$CLOUD_DIR/webapps/arda/.env`.

**Do not proceed to Step 3 until the check reports 0 issues.**

### Step 3: Launch the webpack watcher and arda-server (both in background)

> ⚠️ **Critical — both MUST use `run_in_background: true`**
> Both commands below are long-running daemons that never exit on their
> own (`webpack --watch` and `nodemon`). Launching either in the
> foreground will hang the skill indefinitely. Capture the task ID each
> one returns.

Launch the webpack watcher:

```bash
cd "$CLOUD_DIR" && yarn dev:arda-webpack
```

Launch arda-server — **don't wait for webpack first**. The server will
happily start while webpack is still doing its initial compile; express
just serves whatever's in `dist/` (and returns 404 for missing files
until webpack finishes, which takes ~10–15s total). The parallelism
is fine:

```bash
cd "$CLOUD_DIR" && yarn dev:arda-server
```

### Step 4: Poll port 3010, then open the browser

arda listens on port **3010** by default (see
`webapps/arda/arda.js:app.set("port", process.env.PORT || 3010)`).
Honour the user's `PORT` if set in `.env`.

A single poll loop covers both "server is up" and "webpack's first
compile has landed" — by the time port 3010 accepts connections, arda
is typically serving the bundle too.

```bash
# Wait up to 90s — covers cold server start + cold webpack build
for i in $(seq 1 45); do
  if curl -sf -o /dev/null -m 2 "http://localhost:3010/"; then
    echo "arda is up"; break
  fi
  sleep 2
done

# Open in the default browser (Windows)
start "" "http://localhost:3010/"
```

If the port never responds, read **both** background task output files
to diagnose. On Windows, reference the paths with forward slashes or
single quotes — `\U`, `\A`, `\T` etc. inside double-quoted strings are
mangled by bash's escape handling:

```bash
# Use forward slashes (bash-safe) or single quotes
grep -iE 'error|cannot find|EADDRINUSE' 'C:/Users/.../tasks/<server-id>.output'
grep -iE 'error|cannot find|EADDRINUSE' 'C:/Users/.../tasks/<watcher-id>.output'
```

Common failure signatures:
- `EADDRINUSE` — something else is on port 3010; ask user to kill it or
  set `PORT` in `.env`
- `Cannot find module 'X'` from webpack — Step 2a's install missed a
  package; ask user to re-run `yarn install` in `$CLOUD_DIR/webapps`
- Missing `.env` key — a required variable wasn't set; user must edit
  `.env`

Do not try to fix — diagnose, report, hand back to the user.

### Step 5: Confirm and hand off

Tell the user:

- arda is running at `http://localhost:3010`
- Two background processes are live: arda-server and the webpack watcher
- Saving a file under `webapps/arda/` will trigger a rebuild + server
  restart automatically
- To stop, kill the background shells (give the user the shell IDs)

### Step 6: Handoff to other skills

- Building a feature on top of arda? → `/bigstack-arda-feature`
- Need the full cloud stack, not just arda? → `/bigstack-cloud-setup`
- Visually QA'ing arda in the browser? → `/bigstack-browse` or
  `/bigstack-david-design-review`

## Confidence Calibration

Before completing a major action, state your confidence:

| Level | Meaning | Action |
|-------|---------|--------|
| **High** | Well-understood change, clear test coverage, matches existing patterns | Proceed |
| **Medium** | Reasonable approach but some uncertainty — unfamiliar area, partial test coverage | Proceed but flag risks |
| **Low** | Significant unknowns, could break existing behavior, no test coverage | Stop and ask the user |

Format: **Confidence: [High/Medium/Low]** — [one-line rationale]