diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1138622 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# AGENTS - sky_phone + +## Scope + +This repository contains the standalone FiveM resource `sky_phone`. These rules +apply throughout the repository unless a more specific `AGENTS.md` adds stricter +requirements. + +## Architecture and security + +- Keep `sky_phone` independent. Do not add dependencies or integrations with + `sky_base`, `sky_jobs_base`, or other `sky_*` resources. +- Keep resource-owned configuration, persistence, callbacks, events, and + framework abstractions inside `sky_phone`. +- Prefix new resource-owned callbacks and events with `sky_phone:`. +- Keep client, server, and shared responsibilities separate. Prefer a local + function when an export or network event is unnecessary. +- Treat all client and NUI input as untrusted. The server must authorize every + state-changing action involving identity, permissions, ownership, money, + inventory, proximity, or configured limits. +- Parameterize SQL and keep database objects owned by this resource. +- Never commit credentials, tokens, private keys, personal data, internal + infrastructure details, or deployment-specific paths. + +## FiveM and Lua + +- Keep `use_experimental_fxv2_oal "yes"` enabled in the resource manifest. +- Pass native coordinates as separate numeric arguments. Do not pass a + `vector3` where a native expects individual coordinates. +- Verify native signatures and use the documented parameter types. +- Use `joaat("...")`, `PlayerPedId()`, and vector distance where applicable. +- Treat native results as truthy or falsy values instead of comparing them with + `true` or `false`. +- Avoid unconditional per-frame loops. Sleep while idle and use `Wait(0)` only + while per-frame work is required. +- Keep failures visible in concise English diagnostics instead of silently + swallowing invalid states. + +## Frontend and NUI + +- Use Vue 3 Composition API with TypeScript and the existing stores and router. +- Use the shared Sky UI through `@/ui` for new or substantially changed screens. + Export reusable primitives through the relevant UI indexes. +- Do not add new direct `konsta/vue` imports. +- Use the shared semantic tokens and stylesheet order. Avoid duplicating common + colors, spacing, radii, safe areas, or interaction geometry in app-local CSS. +- Localize all user-facing text through the phone locale system. Keep logs and + developer diagnostics in English. +- Every NUI callback must invoke its response callback on every reachable path. +- Preserve one intended vertical scroll owner, visible keyboard focus, reduced + motion support, and interaction targets of at least 44 CSS pixels. +- FiveM CEF is the runtime contract. Keep critical behavior compatible with the + configured browser target and do not treat a desktop preview as live FiveM + proof. +- Do not hand-edit generated frontend output. + +## Working method and verification + +1. Trace the relevant client, server, NUI, configuration, persistence, and event + flow before changing behavior. +2. Fix the root cause with the smallest coherent change while preserving public + compatibility unless the task explicitly changes it. +3. Verify external APIs and integrations against their current source or + authoritative documentation. +4. Run the narrowest relevant checks and inspect the final diff. + +For frontend changes, use the scripts declared in `frontend/package.json` as +appropriate, including type checking, linting, tests, and the production build. +Report build or browser-preview evidence separately from live in-game testing. + +## Git + +- Use `TAG - short imperative summary` for commit subjects. +- Supported tags are `ENH`, `ADD`, `FIX`, `DOC`, `BLD`, `PERF`, `CLN`, and `TRY`. +- Keep commits focused and document required configuration, locale, or database + migrations. +- Stage only files belonging to the task and preserve unrelated worktree + changes.