docs: Document ActivityService and system message architecture in AGENTS.md and DECISIONS.md

AGENTS.md

@@ -58,6 +58,12 @@ This project has domain-specific skills available in `**/skills/**`. You MUST ac
 - Stick to existing directory structure; don't create new base folders without approval.
 - Do not change the application's dependencies without approval.
 
+## Activity Service
+
+- The `app/Services/ActivityService.php` class is used to create system messages and activities.
+- To create a system message, use the `createMessage` method. The `$user` parameter should be `null` to indicate a system message.
+- The `createMutation` method can be used to create a mutation and its associated system message.
+
 ## Frontend Bundling
 
 - If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them.

DECISIONS.md

@@ -53,6 +53,12 @@ We implemented a secure Dynamic Invitation flow to allow owners to invite new me
     ```
 *   **Access Control:** Access to invitations and creation is fully protected under Owner-only authorization checks.
 
+### 7. Centralized Activity Service for System Messages
+We created `app/Services/ActivityService.php` to centralize the creation of system messages and activities.
+*   **System Messages as `null` user_id**: System messages are stored as `Message` records with a `null` `user_id`, cleanly distinguishing them from user-generated content.
+*   **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.
+
 ## Initial Database Schema
 
 I will start with a basic schema and evolve it as I build features.