---
name: star-site-integration
description: "Integrate a frontend site with the Star platform: Star Auth login and token refresh, Star Task AI image/video/audio/chat tasks, unified point charging, R2-backed results, model/pricing discovery, and PV/UV analytics. Use when building, migrating, reviewing, or debugging a site registered in Star Admin."
---

# Star Site Integration

Use the Star public contracts. Do not call RokoAPI or any upstream provider from a frontend site, and do not reproduce point-consumption logic in the frontend.

## Workflow

1. Ask for or locate the assigned `site_id` and registered production origin.
2. Read [configuration.md](references/configuration.md) and implement Star Auth first.
3. Read [tasks.md](references/tasks.md) when the site creates AI tasks. Discover models and pricing at runtime; never hard-code provider names or point costs.
4. Read [analytics.md](references/analytics.md) and enable PV/UV reporting on every public page except the auth callback.
5. Run every check in [verification.md](references/verification.md) before release.

## Non-negotiable contracts

- Browser login goes through `https://auth.starhk.uk`; AI tasks go through `https://task.starhk.uk`.
- Every protected request carries `Authorization: Bearer <access_token>` and the assigned `site_id`.
- Use a fresh UUID v4 `idempotency_key` for each user-initiated task and reuse it only when retrying that same action.
- Poll the returned `poll_url`; do not construct an upstream task URL.
- Display the `cost_points` returned by Star APIs. Provider routing and charging are server responsibilities.
- Store access/refresh tokens using the host project's established secure pattern. Never expose site secrets, RokoAPI keys, or admin credentials in browser code.
- Treat output URLs returned by Star Task as the stable application URLs. Do not depend on temporary upstream URLs.

## Change discipline

Preserve the host site's existing routing, UI system, and auth state shape. Make the smallest compatible change, then verify login, refresh, task idempotency, charging, result rendering, and analytics independently.