extra documentation updates

DECISIONS.md

@@ -59,6 +59,27 @@ We created `app/Services/ActivityService.php` to centralize the creation of syst
 *   **Polymorphic Subject Linking**: System messages are linked to relevant entities (e.g., a `User` who joined a dynamic, a `Ledger` that was created) via a polymorphic `subject` relationship on the `messages` table. This allows system messages on the dashboard to link directly to the relevant entity.
 *   **Seeder Refactoring**: The `DatabaseSeeder` was refactored to use the `ActivityService` to generate all system messages, ensuring consistency.
 
+### 8. Event-Driven Automated System Logging
+We relocated the dynamic system activity message generation out of individual controller endpoints and into the **Eloquent `Mutation` Model's `booted` -> `created` event hook**.
+*   **Unified generation:** Any mutation creation (whether occurring via a controller submission, an automated Pest test factory, or seeders during `php artisan db:seed`) now automatically and reliably generates correct system log messages.
+*   **Database Seeder fixed:** Reverted the database seeder (`DatabaseSeeder.php`) back to using standard clean Eloquent creations. Since model events automatically trigger, `php artisan db:seed` executes cleanly and builds a rich, fully populated database history with system messages out-of-the-box.
+
+### 9. Standardized Policy-Driven UI Capabilities (`can` prop)
+To maintain strict data security and clean up front-end markup, we eliminated unstandardized, hardcoded client-side role checks (like `isOwner` properties or manual `pivot.role === 'owner'` checks) and replaced them completely with dynamic **policy-driven capabilities** returned directly from Laravel policies as `can` objects.
+*   **Centralized checks:** Both the dynamic and ledger show routes return a standard `can` prop to the frontend (e.g., `can: { update: boolean, close: boolean }`).
+*   **Polymorphic Resource Capabilities:** Each mutation model is wrapped in `MutationResource` which appends its own localized policy checks (`update` for approving suggestions, `void` for voiding) at the individual record level.
+*   **State-based policies:** The `MutationPolicy` methods enforce both ownership authorization and state-based business constraints simultaneously (e.g., a mutation can be approved/updated *only* if its status is currently `'pending'`; and can be voided *only* if its status is not `'voided'`). This keeps the Vue templates purely declarative (e.g., `v-if="mutation.can.update"`) and automatically protects the backend controllers against illegal state transitions.
+
+### 10. Ledger-Scoped Predefined Mutation Templates ("Rewards")
+Predefined mutations act as point-based templates ("purchases" or reusable chores) and belong strictly to specific **Ledgers** instead of broad Dynamics.
+*   **Domain Alignment:** Moving the resource nesting under ledgers (`dynamics.ledgers.predefined-mutations`) aligns perfectly with the mental model of spending points on a ledger.
+*   **Type-Less Rewards:** To simplify both the database schema and UI/UX, we eliminated the explicit `type` column ('reward' vs. 'penalty') from predefined mutations. They act as generic point-carrying "Rewards" whose amount can naturellement be positive (earning points) or negative (making a purchase / deducting points) without requiring restrictive explicit categorization.
+
+### 11. Silent XHR Chat Pagination & Smooth Scrolling UX
+To optimize chat-feed performance and improve overall user experience:
+*   **Silent pagination (No URL pollution):** Rather than using Inertia `router.get` visits which push `?page=x` into the browser URL and break history during page reloads, we implemented a **silent background fetch** (using native browser `fetch()`) that queries our dedicated messages JSON API endpoints and prepends older messages silently to the feed.
+*   **Scroll Preservation:** Added `preserveScroll: true` to the Inertia `form.post` call in `Chat.vue` to prevent the active page scroll position from jumping or shifting when a new message is successfully submitted.
+
 ## Initial Database Schema
 
 I will start with a basic schema and evolve it as I build features.

GEMINI.md

@@ -14,4 +14,19 @@ Welcome to the Ledgerrz codebase! This file defines the persistent guidelines, a
 *   **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:** Powered by Pest PHP (v4). Every backend controller, event, or model change must be validated by running `vendor/bin/pest`.
+*   **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) }
+            ]
+        })
+    });
+    ```

IDEA.md

@@ -40,4 +40,28 @@ During this session, we successfully built out and verified several core archite
 5. **Broadcasts, Environment & Verification**:
    * Configured real-time notifications utilizing Laravel Reverb.
    * Documented CLI environment test pollution learnings inside `AGENTS.md` to prevent future CSRF `419` errors.
-   * Ensured full production assets compilation (`npm run build`) and achieved **45/45 passing Pest PHP tests with 206 assertions**.
+   * Ensured full production assets compilation (`npm run build`) and achieved **45/45 passing Pest PHP tests with 206 assertions**.
+
+6. **Ledger-Scoped Predefined Mutation Templates ("Rewards")**:
+   * Associated reusable point-based predefined mutation templates under specific Ledgers rather than broad Dynamics, mapping perfectly to the mental model of spending points on a ledger.
+   * Designed them purely as "Rewards" with positive or negative point amounts (handling both demerit-purchases and chores), removing the obsolete `type` categorization for a simpler, type-less, and sleeker UI/UX.
+
+7. **User Activity Profiling & Detail Pages**:
+   * Created a dynamic user detail page (`dynamics.users.show`) scoped to each dynamic. It displays a participant's role, custom display name, fallback real name, and a clean chronological listing of their 10 most recent mutations (activities) in that dynamic.
+
+8. **Polymorphic System Message placeholders & Dynamic Client-Side Linking**:
+   * Refactored system log activity messages to use native `<user:userId>` placeholders and associated them with polymorphic `subject_id` and `subject_type` objects.
+   * On the client-side, the chat component parses these placeholders into rich, clickable links to User Profiles, and dynamically matches and wraps referenced ledger names into links pointing directly to the ledger show page.
+   * Added backend-side placeholder resolution inside `ActivityService` for the dashboard, ensuring unread system logs translate cleanly to real names across multiple dynamics.
+
+9. **Vite/Inertia v3 Layout Callback Breadcrumbs**:
+   * Utilized Inertia v3's powerful new layout callback API inside Vue page `defineOptions` to reactively resolve page-specific dynamic breadcrumbs at runtime using parsed page props, making the pages self-contained and keeping PHP controllers beautifully slim.
+
+10. **Silent background Chat Pagination & Smooth Scrolling UX**:
+    * Implemented silent background XHR queries (using native browser `fetch()`) on our dedicated message JSON API routes to load older chat pages, completely bypassing browser history/URL pollution and preserving page state on refreshes.
+    * Integrated `preserveScroll: true` inside chat form submissions to completely prevent scroll jumps when sending messages.
+
+11. **Standardized Policy-Driven UI Capabilities**:
+    * Eliminated unstandardized client-side role checks and boolean flags, replacing them with structured `can` capability objects returned directly from Laravel policies.
+    * Combined permission validation with state-based business constraints in `MutationPolicy` (e.g., suggestions can be approved/rejected only if `'pending'`; and voided only if not `'voided'`), securing both the frontend action buttons and backend controllers simultaneously.
+    * Achieved **65/65 passing Pest PHP tests with 333 assertions**.