# Argus Airsoft — full agent guide

> Extended machine-readable documentation. Summary: [llms.txt](https://argusairsoft.com/llms.txt).

## Product overview

Argus Airsoft is a realtime airsoft operations platform:

- Nationwide US field catalog (521 enriched listings) with map search and country filter
- International field catalog (300+ listings across GB, DE, FR, CA, NL, AT, and more via `npm run seed:international`)
- Honor check-in / check-out at fields
- Live presence rosters via WebSockets (`wss://<host>/ws/fields/:fieldId`)
- Field events (public calendar + owner-managed private events)
- Verified field ownership claims, My Field owner dashboard (analytics, intel inbox, listing edits)
- Field intel routing: verified fields → owner inbox; unverified → Argus pipeline (`npm run intel:list`)
- Curated sponsor network on field pages — 300×250 prebuilt creatives, founding launch pricing (`/advertise` inquiries; agent-managed campaigns)
- Team HQ: roster, loadouts, comms, assignments, notifications, ownership transfer (`wss://<host>/ws/teams/:teamId` with signed subscribe token)
- Player dashboard: XP, check-in history, operator profile (bio, class, unit, Discord), personal gear locker with printable PDF
- Privacy Policy and Terms for web, iOS, and Android (MR Dula Enterprise, LLC, 13+)

## URL structure

All user-facing pages use locale prefixes: `/{locale}/...` where locale is one of: en, es, de, pl.
Default locale: `en`. Root `/` redirects to `/en`.

HTTP API and WebSocket routes are **not** locale-prefixed — always call `/api/...` and `/ws/...` directly.
If a client accidentally requests `/{locale}/api/...`, middleware rewrites it to the canonical `/api/...` path.

## Authentication

- Provider: [Clerk](https://clerk.com)
- Header: `Authorization: Bearer <session_jwt>`
- Public read endpoints do not require auth
- Mutations (check-in, claims, team ops, gear locker) require a valid Clerk session

## Public HTTP API

- **/api/health** — Health check and API version
- **/api/fields** — List/search fields; query country, state, q, live
- **/api/fields/live** — Bulk live check-in counts
- **/api/fields/{slug}** — Field detail and presence snapshot
- **/api/fields/{slug}/presence** — Live roster (callsigns only)
- **/api/events** — Upcoming public events
- **/api/fields/{slug}/events** — Events for a field
- **/api/teams** — Public team listings
- **/api/teams/{slug}** — Team detail
- **/api/ads/active** — Active curated sidebar ad(s) for field pages; query slot=field_sidebar
- **/api/ads/inquiries** — POST advertise inquiry (public)
- **/api/fields/{slug}/view** — POST page view (deduped; owners excluded)
- **/api/events/invite/{token}** — Private event invite landing data

## Authenticated HTTP API (summary)

- `/api/me`
- `/api/me/field-access`
- `/api/me/gear`
- `/api/me/gear/{id}`
- `/api/fields/{slug}/checkin`
- `/api/fields/{slug}/checkout`
- `/api/fields/{slug}/claim`
- `/api/fields/{slug}/manage`
- `/api/fields/{slug}/verify`
- `/api/fields/{slug}/analytics`
- `/api/fields/{slug}/intel`
- `/api/teams/mine`
- `/api/teams/join`
- `/api/teams/{slug}/join-requests/{userId}`
- `/api/teams/me`
- `/api/teams/{slug}/messages`
- `/api/teams/{slug}/attachments`
- `/api/media/teams/{path}`
- `/api/teams/{slug}/locations`
- `/api/teams/{slug}/assignments`
- `/api/teams/{slug}/notifications`
- `/api/teams/{slug}/transfer`
- `/api/teams/{slug}/ws-token`

Full contract: [OpenAPI 0.7.0](https://argusairsoft.com/openapi/argus.openapi.yaml)

## Realtime

| Channel | Path | Data |
|--------|------|------|
| Field presence | `/ws/fields/:fieldId` | Live check-in count and roster updates |
| Team comms | `/ws/teams/:teamId` | Messages and HQ events for members |

## MCP server (`mcp/argus-airsoft`)

Stdio MCP server wrapping the HTTP API. Configure `ARGUS_API_URL` (default `http://localhost:3000`) and `ARGUS_BEARER_TOKEN` for authenticated tools.

Server card: https://argusairsoft.com/.well-known/mcp/server-card.json

### Fields

- `argus_health`
- `argus_list_fields`
- `argus_get_field`
- `argus_get_field_presence`
- `argus_list_live_field_counts`

### Field events

- `argus_list_public_events`
- `argus_list_field_events`
- `argus_create_field_event`
- `argus_update_field_event`
- `argus_delete_field_event`

### Field ownership

- `argus_get_field_claim_status`
- `argus_submit_field_claim`
- `argus_get_field_analytics`
- `argus_update_owned_field`

### Profile and check-in

- `argus_get_profile`
- `argus_update_profile`
- `argus_check_in`
- `argus_check_out`
- `argus_verify_field`

### Gear locker

- `argus_list_gear_items`
- `argus_create_gear_item`
- `argus_update_gear_item`
- `argus_delete_gear_item`

### Teams

- `argus_list_teams`
- `argus_get_team`
- `argus_create_team`
- `argus_join_team`
- `argus_leave_team`
- `argus_update_my_loadout`

### Team HQ

- `argus_review_join_request`
- `argus_assign_team_member`
- `argus_remove_team_member`
- `argus_regenerate_team_invite`
- `argus_list_team_messages`
- `argus_send_team_message`
- `argus_list_team_assignments`
- `argus_create_team_assignment`
- `argus_update_team_assignment`
- `argus_list_team_notifications`
- `argus_mark_team_notifications_read`
- `argus_broadcast_team_announcement`

## Privacy and data handling

- Operator: MR Dula Enterprise, LLC. Contact: matt@mrdula.solutions
- Public field rosters: callsign or "Operator" only — no emails
- Team private data requires membership
- Field owners can create private events visible only when authenticated as owner
- User contributions (field intel, claims, team content) must be accurate and lawful; see Terms
- Do not scrape authenticated pages; use the API with user consent
- Legal: [Privacy Policy](https://argusairsoft.com/en/privacy) · [Terms](https://argusairsoft.com/en/terms)

## SDK

TypeScript client: `@argus/sdk` in `packages/argus-sdk`. Preferred reference for native apps; generate platform clients from OpenAPI when needed.

## Mobile (iOS + Android)

Native apps are **not** the Next.js web UI. Before building iOS or APK:

- **Mobile agent guide:** [llms-mobile.txt](https://argusairsoft.com/llms-mobile.txt) (also `platforms/mobile/AGENTS.md` in repo)
- **Scope:** Player + team features via API/WebSockets; **not** ads, MCP, admin CLIs, or field-owner dashboard (web/browser for owners v1)
- **Roadmap:** [platforms/ROADMAP.md](https://github.com/mrdulasolutions/argusairsoft/blob/main/platforms/ROADMAP.md) — mobile column
- **Future:** Team field ops (TAK-style) — spec in `platforms/mobile/features/team-field-ops.md`; API TBD

## Contact and source

- Repository: https://github.com/mrdulasolutions/argusairsoft
- API health: https://argusairsoft.com/api/health