Adhere to these fundamental principles in all development activities:

1. Simplicity First (KISS & YAGNI):

   • Always seek the simplest practical solution.
   • Prioritize Functionality Sources:
     1. Built-in Nuxt 3 features (auto-imports, composables, utilities).
     2. Functionality from installed Nuxt modules (e.g., shadcn-nuxt, PWA).
     3. Utilities from already installed packages (e.g., @vueuse/core, zod).
     4. New Dependencies (Last Resort): Only add new packages or modules if essential functionality cannot be reasonably achieved otherwise. Justify any new additions.
   • Avoid unnecessary features or complexity. If you don't need it now, don't build it.

2. Client-Side Rendering (CSR) & PWA Focus:

   • The application is primarily CSR. Design components and logic for the client environment.
   • Server-Side Rendering (SSR) is an exception, used only for essential online-only operations like authentication (/login, /auth/**).
   • Prioritize fast initial load times (First Contentful Paint, Time To Interactive) and smooth client-side interactions.
   • Implement robust loading states (e.g., skeleton components) and user-friendly error states for all asynchronous operations or data fetching.

3. Offline-First Design:

   • Strive to make all features as functional as possible without an internet connection.
   • Utilize useSecureStorage extensively for encrypted client-side data persistence, making user data and application state available offline.
   • Implement intelligent data synchronization: load from local cache first, then update from the network when online. Keep data fresh without disrupting the user experience.
   • Leverage useDebounce where appropriate (e.g., user input, frequent state updates) to optimize performance and reduce unnecessary operations.
   • Strictly follow PWA best practices for caching, service workers, and background sync (see pwa-rules.mdc).

4. Reusability (DRY - Don't Repeat Yourself):

   • Before creating new components, composables, or utilities, check if existing ones can be reused or adapted.
   • Promote the use of shared composables in /composables for cross-cutting concerns.

5. Elegance & Intuitiveness (SINE):

   • Write clean, readable, and maintainable code.
   • Design intuitive user interfaces and application flows.

6. Security (SINE):

   • Prioritize the security of user data, especially when stored client-side via useSecureStorage.
   • Follow security best practices for API interactions and data handling.

Architecture & Structure

Maintain the established project structure and architectural patterns:

1. Project Structure:

   • Adhere to the defined directory layout (/components, /composables, /pages, /server, /types, etc.). Place files in their designated locations.

2. UI & Styling:

   • Component Library: Use shadcn-vue components (located in components/ui/) as the foundation for all UI elements. These are auto-imported; do not import them manually.
   • Styling: Use Tailwind CSS utility classes exclusively. Adhere to the theme variables defined in assets/css/tailwind.css and tailwind.config.js.
   • Theming: Ensure all components respect light/dark modes using the defined CSS variables.
   • Glass Effects: Apply glass effect classes (glass-effect, glass-card, etc.) consistently as defined in tailwind.css.
   • Refer to ui-components-rules.mdc for detailed UI guidelines.

3. Data Management & Storage:

   • Database: Use Prisma ORM for server-side database operations via API endpoints.
   • Media/Object Storage: Interact with Linode Object Storage (S3 compatible) only through the useAppStorage composable for media files.
   • Persistent Client Storage: Use useSecureStorage for all sensitive or persistent client-side data that needs to be available offline. Data is automatically encrypted.
   • Temporary Client State: Use useMemoryStorage or standard Vue refs/reactives (useState for shared state) for temporary, non-sensitive UI state or draft data.
   • Refer to storage-rules.mdc for comprehensive storage rules.

4. State Management:

   • Local: Use Vue Composition API (ref, computed, reactive) within components.
   • Shared (Client-side): Use Nuxt's useState for simple state sharing between components within the client session.
   • Persistent: Use useSecureStorage for state that needs to persist across sessions and be available offline.

Development Practices

Follow these practices during implementation:

1. Component Design:

   • Build components with a single responsibility.
   • Always include appropriate loading, error, and offline states. Use skeleton loaders for a better user experience.

2. Data Fetching:

   • Use the standard useAsyncData or $fetch patterns optimized for CSR and offline use:
     • Always use server: false.
     • Implement cache-first logic (check useSecureStorage before network).
     • Provide default data structures.
     • Refresh data in the background when online.
     • Use lazy: true for non-critical data.
   • Refer to pwa-rules.mdc for detailed patterns.

3. Error Handling:

   • Implement robust and user-friendly error handling throughout the application.
   • Distinguish between network errors, API errors, and application errors.
   • Provide clear feedback and recovery options (e.g., retry buttons).
   • Handle offline scenarios gracefully.
   • Refer to error-handling-rules.mdc.

4. API Integration:

   • Interact with server API endpoints consistently.
   • Design APIs and client-side logic to support offline data queuing and background synchronization.
   • Refer to api-integration-rules.mdc.

5. Imports:

   • Do Not Import Auto-Imports: Never manually import functions/components auto-imported by Nuxt 3 or Vue (e.g., ref, computed, defineNuxtConfig, Button, Input).
   • Use type-only imports (import type { ... }) where appropriate.

6. Nuxt Best Practices:

   • Follow established Nuxt 3 conventions and best practices.
   • Keep Nuxt 4 compatibility in mind where practical, but prioritize clean Nuxt 3 implementation.

7. Caching:

   • Leverage caching at multiple levels: Service Worker (asset/API caching), useSecureStorage (data caching), useAsyncData (built-in caching).
   • Implement intelligent caching strategies (e.g., stale-while-revalidate) where appropriate.

8. Testing:

   • Write tests as needed, focusing on critical functionality, composables, and utility functions. Utilize Vitest and related testing libraries integrated into the project.