fix: Use incremental ID

heromodels_core/src/lib.rs

@@ -86,9 +86,47 @@ pub trait Index {
 }
 
 /// Base struct that all models should include
+///
+/// # ID Management
+///
+/// The `id` field is managed automatically by OurDB when using incremental mode:
+///
+/// 1. When creating a new model, the `id` field is initialized to 0.
+/// 2. When saving the model to the database with `set()`, OurDB will:
+///    - If the ID is 0, auto-generate a new ID and update the model.
+///    - If the ID is not 0, use the provided ID for updates.
+///
+/// # Important Notes
+///
+/// - Never manually set the `id` field to a specific value. Always use 0 for new models.
+/// - The ID 0 is reserved for new models and should not be used for existing models.
+/// - After saving a model, use the ID returned by `set()` to retrieve the model from the database.
+/// - The original model passed to `set()` is not modified; you need to retrieve the updated model.
+///
+/// # Example
+///
+/// ```rust
+/// // Create a new model with ID 0
+/// let user = User::new()
+///     .username("johndoe")
+///     .email("john.doe@example.com")
+///     .build();
+///
+/// // Save the model and get the assigned ID
+/// let user_id = db.collection().set(&user).expect("Failed to save user");
+///
+/// // Retrieve the model with the assigned ID
+/// let db_user = db.collection().get_by_id(user_id).expect("Failed to get user");
+/// ```
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BaseModelData {
     /// Unique incremental ID - will be auto-generated by OurDB
+    ///
+    /// This field is automatically managed by OurDB:
+    /// - For new models, set this to 0 and OurDB will auto-generate an ID.
+    /// - For existing models, this will be the ID assigned by OurDB.
+    ///
+    /// Do not manually set this field to a specific value.
     pub id: u32,
 
     /// Unix epoch timestamp for creation time