ledgerrz/GEMINI.md

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:

  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:

  defineOptions({
      layout: (props: any) => ({
          breadcrumbs: [
              { title: 'Dynamics', href: route('dynamics.index') },
              { title: props.dynamic.name, href: route('dynamics.show', props.dynamic.id) }
          ]
      })
  });