improve auth policy

AGENTS.md

@@ -527,3 +527,59 @@ GET /properties/{propertyId}/bookings/{bookingId}/balance
 ## 7) Compose Notes
 
 - Use `androidx.compose.foundation.text.KeyboardOptions` for keyboard options imports.
+
+---
+
+## 8) Engineering Structure & Anti-Boilerplate Rules
+
+### Non-negotiable coding rules
+
+- Never add duplicate business logic in multiple files.
+- Never copy-paste permission checks, navigation decisions, mapping logic, or API call patterns.
+- If similar logic appears 2+ times, extract shared function/class immediately.
+- Prefer typed models/enums over raw strings for roles/status/flags.
+- Keep files small and purpose-driven; split before a file becomes hard to scan.
+
+### Required project structure (current baseline)
+
+- `core/` -> cross-cutting business primitives/policies (e.g., auth policy, role enum).
+- `data/api/core/` -> API client, constants, token providers, aggregated API service.
+- `data/api/service/` -> Retrofit endpoint interfaces only.
+- `data/api/model/` -> DTO/request/response models.
+- `ui/navigation/` -> route model, navigation orchestrators, back-navigation rules.
+- `ui/<feature>/` -> screen + state + viewmodel for that feature.
+
+### How to implement future logic (mandatory workflow)
+
+1. Define/extend domain type first (enum/data model/policy) instead of raw literals.
+2. Add/extend API contract in `data/api/service` and models in `data/api/model`.
+3. Add shared logic once (policy/helper/mapper) in `core` or feature-common layer.
+4. Keep ViewModel thin: orchestrate calls, state, and errors only.
+5. Keep UI dumb: consume state and callbacks; avoid business rules in composables.
+6. If navigation changes, update `ui/navigation` only (single source of truth).
+7. Before finishing, remove any newly introduced duplication and compile-check.
+
+### PR/refactor acceptance checklist
+
+- No repeated role/permission checks across screens.
+- No repeated model mapping blocks (extract mapper/helper).
+- No giant god-file when it can be split by domain responsibility.
+- Imports/packages follow the structure above.
+- Build passes: `./gradlew :app:compileDebugKotlin`.
+
+### Guest Documents Authorization (mandatory)
+
+- View access: `ADMIN`, `MANAGER` (and super admin).
+- Modify access (upload/delete): allowed only when booking status is `OPEN` or `CHECKED_IN`.
+- For `CHECKED_OUT`, `CANCELLED`, `NO_SHOW`: documents are read-only.
+- Never couple guest document permissions with Razorpay/settings permissions.
+
+### Permission design guardrail
+
+- Do not reuse one feature's permission gate for another unrelated feature.
+- Add explicit policy methods in `core/auth/AuthzPolicy` for each feature capability.
+
+### Refactor safety rule
+
+- Any package/file movement must include import updates in same change.
+- After refactor, compile check is mandatory: `./gradlew :app:compileDebugKotlin`.