initial: bootstrap from BukidBountyApp base

.claude/plans/11d5e96ea355332d03f0b8f8d63dd642-complete.md

@@ -0,0 +1,37 @@
+---
+task: Fix /pos-main showing POS UI shell to unauthenticated users with confusing "Failed to load products" error — improve empty/no-auth state
+cycles: 3
+context: true
+private: false
+started: 2026-05-16T15:59:57Z
+finished: 2026-05-16T16:01:00Z
+---
+
+## files
+- app/Http/Controllers/Support/VueRouteMap.php [lines 93-97] — `/pos` route has `loginRequired: false` (intentional for POS_TERMINAL access key auth)
+- resources/js/Pages/PosMain.vue — POS interface; shows "Failed to load products" when no session/access key is present
+- resources/js/composables/Market/usePosSession.js — session initialization; sets `posStore.error` when no store can be resolved
+
+## steps
+1. In `PosMain.vue`, when `posStore.error` is set AND there is no `pos_access_key` in localStorage AND the user is not logged in, show a clear "No terminal access" message instead of the bare "Failed to load products" error.
+   - Check: `!userStore.isLoggedIn && !posStore.activeSession && posStore.error`
+   - Display: "This terminal has no active session. Please use your POS access key or log in."
+2. (Optional / discuss with owner): Consider adding `allowedUserTypes: ['pos terminal', 'store owner', 'store manager', 'operator', 'super operator', 'ult']` to the `/pos` route while keeping `loginRequired: false`, so the route map at least documents who is expected to use this page.
+
+## context
+Current behaviour (confirmed by Playwright): navigating to `/pos-main` without any session or access key renders the full POS UI shell with:
+- "All | Current Order" tab bar
+- "Start New Session" button
+- "Failed to load products" error banner
+- Empty cart with ₱0.00 totals
+
+This is because `loginRequired: false` is intentional — POS_TERMINAL accounts authenticate via access key (localStorage `pos_access_key`, prefix `PK-`), not via the standard mobile/password login. The backend guards on the actual API calls (start session, add item, etc.).
+
+The UI concern: unauthenticated browsers with no access key see a confusing broken state. The fix is a graceful empty state, not removing `loginRequired: false`.
+
+Dictionary reference: "POS Access Keys: A unique key used to authenticate a POS terminal without a traditional login." and `startNewSessionSilently` guards against calling the API when both `storeHash` and `access_key` are absent.
+
+## notes
+- dictionary: ai-docs/dictionary.md
+- linters: none
+- constraints: Do NOT change `loginRequired: false` on `/pos` — this breaks POS_TERMINAL access key auth. Only improve the UI empty state.