diff --git a/GEMINI.md b/GEMINI.md
index a17475ee..48d59e60 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -36,6 +36,27 @@ The following directories are ignored for various operations (e.g., search, file
 - `node_modules`
 - `tests`
 
+## Development Guidelines
+
+### Svelte v5 and SvelteKit
+
+This project uses Svelte v5 with runes enabled. This introduces significant differences from Svelte v4. It is critical to adhere to v5 conventions to avoid bugs.
+
+-   **Reactivity:** State is managed with `$state` and `$derived`. Props can be made two-way bindable with `$bindable`. Avoid direct mutation of props.
+-   **Event Handling:**
+    -   DOM events still use the `on:eventname` directive (e.g., `on:click`, `on:input`).
+    -   Component events are dispatched with `createEventDispatcher` and listened to with `on:eventname`.
+    -   For two-way binding on component props, use `bind:propName`.
+-   **Stores and `liveQuery`:**
+    -   To access the value of a store in Svelte v5, you must use the `$store_name` syntax (e.g., `$ae_api`).
+    -   Dexie `liveQuery` returns an observable. To use it in a component, you must subscribe to it within `onMount` to avoid SSR errors. The value from the subscription should then be assigned to a `$state` variable.
+-   **Migration Guide:** For a comprehensive overview of the changes, refer to the official [Svelte 5 Migration Guide](https://svelte.dev/docs/svelte/v5-migration-guide).
+
+### ID Convention: `id` vs. `id_random`
+
+-   **Always use `id_random`:** The API returns both a numeric `id` and a string-based `[obj_type]_id_random`. For all frontend operations (routing, data fetching, local storage), you **must** use the `_id_random` string.
+-   **Local Storage:** When saving an object to the local IndexedDB (Dexie), the `id_random` value should be aliased to both `id` (as the primary key) and `[obj_type]_id`. This ensures consistency with Dexie's expectations and the rest of the application's data access patterns.
+
 ---
 
 ## Refactoring Notes