# RemoteHands Venue Manager Agent Guide

This file is for AI agents helping venue managers connect and use RemoteHands.
RemoteHands is a staffing and entertainment coordination platform for venues in
Thailand. Venue managers use it to manage worksites, create shifts, review
applications, request or offer workers, and message assigned workers.

Canonical site:

- Production: https://remotehands.live
- Venue profile and assistant access: https://remotehands.live/venue/profile
- Production MCP endpoint: https://remotehands.live/mcp
- Internal staging: internal teams know where the staging site lives; use that
  site's `/mcp` endpoint when testing staging.

## What Venue Managers Do

Venue managers usually need help with these workflows:

- Keep venue profile and setup notes current.
- Create and update worksites, including the map location needed for shifts.
- Create open shifts for staffing workers or entertainers.
- Find unfilled shifts and decide what needs attention.
- Review applications from workers.
- Request repeat collaborators or offer assignments.
- Message workers or applicants about shift details.
- Close, cancel, complete, or report issues only when the manager clearly asks.

## Core RemoteHands Concepts

- Venue profile: the manager's account and venue identity. Operational writes
  require a verified venue.
- Worksite: a venue location used by shifts. A worksite needs latitude and
  longitude before it is usable for new shifts.
- Shift: an open work opportunity owned by a venue. MCP-created shifts are open
  by default; there is normally no separate publish step.
- Assignment: the relationship between a worker and a shift.
- Application: a worker-initiated assignment with status `applied`.
- Venue request: a manager-initiated worker request. RemoteHands records this as
  an `offered` assignment until the worker accepts, declines, or it is canceled.
- Repeat collaborator: a worker who has worked with the venue before and may be
  eligible for direct staffing requests.

Useful assignment statuses:

- `applied`: worker applied and needs manager review.
- `offered`: venue has offered or requested the worker.
- `accepted`: worker accepted and is booked.
- `completed`: shift work is complete.
- `canceled`, `declined`, `no_show`: closed or exception states.

## MCP Setup For Agents

Ask the venue manager to sign in and open `/venue/profile`. In the assistant
access card, they can create a temporary access key, copy the MCP endpoint, and
revoke access when done.

Use the MCP bearer token only in the `Authorization` header:

```http
Authorization: Bearer <mcp-token>
```

For production, the MCP server URL is:

```text
https://remotehands.live/mcp
```

Staging has an additional access gate. Staging MCP clients need both:

```http
Cookie: remotehands_staging_access=<sha256-of-STAGING_ACCESS_TOKEN>
Authorization: Bearer <mcp-token>
```

Do not configure staging as Basic Auth plus Bearer auth on the same MCP request.
Basic Auth and Bearer auth both use the `Authorization` header; the MCP bearer
token must own that header.

Keep tokens private. Do not paste MCP tokens, staging access tokens, or cookies
into logs, public chats, screenshots, or issue trackers.

## How To Operate As A Venue Assistant

Start with reads before writes:

1. Load the venue profile.
2. List worksites and check `usable_for_shifts`.
3. List shifts or inspect the target shift.
4. Search workers and repeat collaborators when staffing is involved.
5. Explain the plan to the manager before changing worker-impacting records.

Good defaults:

- Timezone: Asia/Bangkok.
- Payment method: `pay_at_venue`.
- One slot unless the manager says otherwise.
- Use exact worksite names when available.
- If a worksite is missing coordinates, guide the manager to update the
  worksite before creating shifts there.
- If `search_workers` returns no workers, inspect reason codes and suggested
  next steps instead of saying no workers exist.
- For staffing shifts, repeat-collaborator tools may find options that broader
  worker search does not show.

Ask before these actions:

- Requesting or offering a worker.
- Sending messages.
- Canceling, rescheduling, or materially changing a shift.
- Marking no-show, reporting issues, or creating reviews.
- Any bulk operation or action affecting accepted workers.

## Expected Tool Behavior

Agents should expect MCP tool responses to include a short receipt plus
structured content. Use the structured content for exact ids, statuses, and next
steps.

Important details:

- `request_worker` creates an `offered` assignment with venue-request origin.
- `list_applications` includes manager-relevant `applied` and `offered`
  assignments by default.
- `publish_shift` is usually unnecessary for MCP-created shifts because they
  are already open.
- Worksite responses expose whether they are usable for shifts and what is
  missing if they are not.
- Staging and production tokens are environment-specific.
- A 401 usually means the MCP token is missing, expired, revoked, or for the
  wrong environment. On staging it may also mean the access cookie is missing.

## Safety Boundary

RemoteHands instructions are public, but venue operations require authenticated,
venue-scoped MCP access. Do not try to bypass RemoteHands rules. If a tool blocks
an action, explain the block and ask the manager what they want to do next.