# Contributing to The Nexus

Thanks for contributing to Timmy's sovereign home. Please read this before opening a PR.

## Project Stack

- Vanilla JS ES modules, Three.js 0.183, no bundler
- Static files — no build step
- Import maps in `index.html` handle Three.js resolution

## Architecture

```
index.html    # Entry point: HUD, chat panel, loading screen
style.css     # Design system: dark space theme, holographic panels
app.js        # Three.js scene, shaders, controls, game loop (~all logic)
```

Keep logic in `app.js`. Don't split without a good reason.

## Conventions

- **ES modules only** — no CommonJS, no bundler imports
- **Color palette** — defined in `NEXUS.colors` at the top of `app.js`; use it, don't hardcode colors
- **Conventional commits**: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
- **Branch naming**: `claude/issue-{N}` for agent work, `yourname/issue-{N}` for humans
- **One PR at a time** — wait for the merge-bot before opening the next

## Before You Submit

1. Run the JS syntax check:
   ```bash
   node --check app.js
   ```
2. Validate `index.html` — it must be valid HTML
3. Keep JS files under 500 KB
4. Any `.json` files you add must parse cleanly

These are the same checks the merge-bot runs. Failing them will block your PR.

## Running Locally

```bash
npx serve . -l 3000
# open http://localhost:3000
```

## PR Rules

- Base your branch on latest `main`
- Squash merge only
- **Do not merge manually** — the merge-bot handles merges
- If merge-bot comments "CONFLICT": rebase onto `main` and force-push your branch
- Include `Fixes #N` or `Refs #N` in your commit message

## Issue Ordering

The Nexus v1 issues are sequential — each builds on the last. Check the build order in [CLAUDE.md](CLAUDE.md) before starting work to avoid conflicts.

## Questions

Open an issue or reach out via the Timmy Terminal chat inside the Nexus.