refactor: Undeprecate SafeBox.create(), document correct usage, and warn against misuses

Author: Abdul Mateen R I

README.md

@@ -87,16 +87,67 @@ dependencies {
 
 ## Basic Usage
 
+First, provide SafeBox as a singleton:
+
+```kotlin
+@Singleton
+@Provides
+fun provideEncryptedSharedPreferences(@ApplicationContext context: Context): SharedPreferences =
+    SafeBox.create(context, PREF_FILE_NAME) // Replacing EncryptedSharedPreferences
+```
+
+Or use the built-in singleton helper:
+
 ```kotlin
-val safeBox = SafeBox.create(context, fileName = "secure-prefs")
+SafeBoxProvider.init(context, PREF_FILE_NAME)
+val prefs = SafeBoxProvider.get()
+```
 
-safeBox.edit()
+Then use it like any `SharedPreferences`:
+
+```kotlin
+prefs.edit()
     .putInt("userId", 123)
     .putString("name", "Luna Moonlight")
     .apply()
 
-val userId = safeBox.getInt("userId", -1)
-val email = safeBox.getString("email", null)
+val userId = prefs.getInt("userId", -1)
+val email = prefs.getString("email", null)
+```
+
+### Anti-Patterns
+
+#### ❌ Do NOT create multiple SafeBox instances with the same file name
+
+```kotlin
+class HomeViewModel @Inject constructor() : ViewModel() {
+    
+    private val safeBox = SafeBox.create(context, PREF_FILE_NAME) // ❌ New instance per ViewModel
+}
+```
+
+This may cause FileChannel conflicts, memory leaks, or stale reads across instances.
+
+---
+
+#### ⚠️ Avoid scoping SafeBox to short-lived components
+
+```kotlin
+@Module
+@InstallIn(ViewModelComponent::class) // ⚠️ New instance per ViewModel
+object SomeModule {
+    
+    @Provides
+    fun provideSafeBox(@ApplicationContext context: Context): SafeBox =
+        SafeBox.create(context, PREF_FILE_NAME)
+}
+
+class HomeViewModel @Inject constructor(private val safeBox: SafeBox) : ViewModel() {
+
+    override fun onCleared() {
+        safeBox.close() // Technically safe, but why re-create SafeBox for every ViewModel?
+    }
+}
 ```
 
 ## Migrating from EncryptedSharedPreferences

safebox/src/main/java/com/harrytmthy/safebox/SafeBox.kt

@@ -317,6 +317,10 @@ public class SafeBox private constructor(
          *
          * This method handles secure initialization and is recommended for most use cases.
          *
+         * **Common pitfalls:**
+         * - Do NOT create multiple SafeBox instances with the same file name.
+         * - Avoid scoping SafeBox to short-lived components (e.g. ViewModel).
+         *
          * @param context The application context
          * @param fileName The name of the backing file used for persistence
          * @param keyAlias The identifier for storing the key (used to locate its encrypted form)
@@ -328,10 +332,6 @@ public class SafeBox private constructor(
          */
         @JvmOverloads
         @JvmStatic
-        @Deprecated(
-            message = "Use SafeBoxProvider.init(...) and SafeBoxProvider.get() instead.",
-            replaceWith = ReplaceWith("SafeBoxProvider.get()"),
-        )
         public fun create(
             context: Context,
             fileName: String,
@@ -362,6 +362,10 @@ public class SafeBox private constructor(
          * This is useful for testing or advanced use cases where you want to control
          * the encryption mechanism directly.
          *
+         * **Common pitfalls:**
+         * - Do NOT create multiple SafeBox instances with the same file name.
+         * - Avoid scoping SafeBox to short-lived components (e.g. ViewModel).
+         *
          * @param context The application context
          * @param fileName The name of the backing file used for persistence
          * @param keyCipherProvider Cipher used for encrypting and decrypting keys
@@ -372,10 +376,6 @@ public class SafeBox private constructor(
          */
         @JvmOverloads
         @JvmStatic
-        @Deprecated(
-            message = "Use SafeBoxProvider.init(...) and SafeBoxProvider.get() instead.",
-            replaceWith = ReplaceWith("SafeBoxProvider.get()"),
-        )
         public fun create(
             context: Context,
             fileName: String,