# Ledgerrz Project Instructions & Conventions

Welcome to the Ledgerrz codebase! This file defines the persistent guidelines, architectural rules, and context directories loaded in every Gemini session.

---

## 1. Context Persistence Mandate
*   **Business Logic & Goals (`IDEA.md`):** You MUST read and follow the application concept, features, and user workflow goals outlined in `IDEA.md` at the start of any new session.
*   **Design & Architecture Decisions (`DECISIONS.md`):** You MUST strictly adhere to the established style architecture (BEM methodology with scoped styles and `@apply`), package deduplication rules, and controller structures documented in `DECISIONS.md`. Update this file with any new major design decisions made during your session.

---

## 2. Key Technology Stack & Conventions
*   **PHP/Laravel:** PHP 8.4 & Laravel 13. Adhere to typed parameters and return values. Ensure controllers extend properly and use required authorization traits (e.g., `AuthorizesRequests`).
*   **Frontend Styling (BEM):** Replaced direct Tailwind inline utility-class markup with **BEM (Block, Element, Modifier)**. All custom component styles must live inside `<style scoped>` blocks with a relative `@reference "../../css/app.css"` directive to pull variables without duplications.
*   **Real-time Broadcasting:** Powered by `@laravel/echo-vue` with fallback configurations and Vite deduplication rules configured in `vite.config.ts`.
*   **Testing & Isolation:** Powered by Pest PHP (v4). Every backend controller, event, or model change must be validated by running tests. To prevent local `.env` variables from polluting the CLI test execution (causing CSRF/session 419 errors), **always** run tests in an isolated environment using:
    ```bash
    env -i PATH="$PATH" php artisan test
    ```
*   **Standardized Authorization (`can` prop):** Never write manual role checks (such as `pivot.role === 'owner'`) or hardcoded boolean flags (such as `isOwner`) inside Vue pages or components. Instead, always leverage Laravel policies on the backend and pass permissions reactively to the frontend as structured `can` objects (e.g., `can: { update: boolean, close: boolean }`).
*   **Vue-Defined Breadcrumbs Layout:** All page-specific breadcrumbs should be declared locally inside the page's `.vue` file rather than returned from controllers. For dynamic, prop-dependent paths, always use the Inertia v3 layout callback function inside `defineOptions`:
    ```typescript
    defineOptions({
        layout: (props: any) => ({
            breadcrumbs: [
                { title: 'Dynamics', href: route('dynamics.index') },
                { title: props.dynamic.name, href: route('dynamics.show', props.dynamic.id) }
            ]
        })
    });
    ```