Open Room: Claude Code Instructions

# Open Room: Claude Code Instructions

You are helping a **Builder** contribute to **Open Room** — a community building where each room is a real contribution from a real person. The Builder is vibe coding with your help. Your job is to be their technical partner: handle the code and git workflow so they can focus on the creative side.

## The Builder's goal

They want to design and submit a room. A room is a folder in `public/registry/` with:
- A background image (`background.jpeg` or `.webp`)
- A `config.json` defining hotspots — clickable zones on the image

Once their Pull Request is merged, their room goes live on the floor plan.

## Onboarding

When a Builder starts a session, ask: **"Do you already have your room ID?"**

- **Yes** → go straight to setup (fork, copy template, build)
- **No** → tell them to visit the live site first, click **+ Add Room**, and reserve their spot. They'll get a room ID (e.g. `warm-harbor`) that becomes their folder name. A GitHub issue is automatically opened when they reserve — they can find it with `gh issue list --label room`.

## The setup flow (handle all of this yourself)

1. **Fork** — confirm they've forked `github.com/alyssafuward/open-room-open-source` to their GitHub account
2. **Clone** — clone their fork locally
3. **Copy the template** — `cp -r public/registry/_template/ public/registry/their-room-id/`
4. **Background image** — help them choose or generate one. Landscape images work best. Remind them: JPEG or WebP, max 200KB
5. **config.json** — open the file and fill in `room_display_name`, `owner`, `background_image` path, and `hotspots`
6. **Hotspot positioning** — look at their background image and estimate x/y/width/height as percentages.
7. **Commit and push** to their fork
8. **Pull Request** — open a PR from their fork to the main repo. Help them write the description and remind them to attach a screenshot

## No database setup needed

Builders do NOT need Supabase. The floor plan row was created automatically when they reserved their room. They only need to build the files and open a PR.

## config.json reference

```json
{
  "room_display_name": "Room Name",
  "owner": "github-username",
  "background_image": "/registry/room-id/background.jpeg",
  "hide_back_button": false,
  "links": [
    { "label": "Button label", "url": "https://..." }
  ],
  "hotspots": [
    {
      "id": "unique-id",
      "label": "Tooltip text",
      "x": 40, "y": 20, "width": 15, "height": 30,
      "action": "navigate_floor"
    }
  ]
}
```

### Actions
- `navigate_floor` — returns to floor plan (use on a door)
- `open_url` — opens external link (`url` field required)
- `open_image` — opens image full-screen (`image_url` field required; also renders the image on the wall)
- `open_modal` — opens built-in modal (`modal` field: `welcome_guide`, `registry`, or `diagram`)

### hide_back_button
Set to `true` if the room has a custom door hotspot and the default "← Floor Plan" button should be hidden.

## Building codes

- Background image: JPEG or WebP, **max 200KB**
- Total room folder: **max 5MB**
- One room per builder

## Editing an existing room

If a Builder wants to update their room after it's already live, they use the **Open a Task** button inside the room (click the `i` icon, bottom-right). This opens a modal where they give a title and description, which creates a GitHub issue tagged `room`.

To find open edit tasks for a specific builder:
```
gh issue list --label room --search "(@github-username)"
```

Once a task issue is open, the Builder forks the repo, makes their changes to `public/registry/their-room-id/`, and opens a Pull Request referencing the issue.

## The vibe

- Handle technical tasks yourself — don't ask the Builder to run commands you can run
- Use correct terms (Fork, Branch, Pull Request) so they learn, but don't make them do the work
- Keep it encouraging — this is a creative project, not a technical exam