docs: add error-handling section to README and introduce SECURITY.md

Author: mCodex

README.md

@@ -31,6 +31,7 @@ Modern secure storage for React Native, powered by Nitro Modules. Version 6 ship
 - [⚡️ Quick start](#-quick-start)
 - [📚 API reference](#-api-reference)
 - [🔐 Access control & metadata](#-access-control--metadata)
+- [❗ Error handling](#-error-handling)
 - [🧪 Simulators and emulators](#-simulators-and-emulators)
 - [📈 Performance benchmarks](#-performance-benchmarks)
 - [🎮 Example application](#-example-application)
@@ -219,6 +220,47 @@ function YourComponent() {
 
 For comprehensive examples and advanced patterns, see [`HOOKS.md`](./HOOKS.md).
 
+## ❗ Error handling
+
+Every public hook returns failures as `HookError` instances. Besides `message`, each error carries:
+
+- `operation` – the hook action that failed (for example, `useSecureStorage.saveSecret`).
+- `cause` – the original native error for additional diagnostics.
+- `hint` – a short suggestion shown in the example app and useful for toast copy.
+
+Biometric or device-credential prompts cancelled by the user now surface as a friendly message (`Authentication prompt canceled by the user.`) and *do not* poison hook state. Imperative calls still reject with the raw error so you can decide how to react.
+
+```tsx
+import { Text } from 'react-native'
+import { useSecureStorage } from 'react-native-sensitive-info'
+
+function SecretsList() {
+  const { items, error } = useSecureStorage({ service: 'auth', includeValues: true })
+
+  if (error) {
+    if (error.message.includes('Authentication prompt canceled')) {
+      return <Text>The user dismissed biometric authentication.</Text>
+    }
+
+    return (
+      <Text testID="secure-error">
+        {error.message}
+        {'\n'}Hint: {error.hint ?? 'Check your secure storage configuration.'}
+      </Text>
+    )
+  }
+
+  return items.length === 0 ? (
+    <Text>No secrets stored yet.</Text>
+  ) : (
+    <Text>{items.map((item) => item.key).join(', ')}</Text>
+  )
+}
+```
+
+> [!TIP]
+> When using the imperative API, look for the `[E_AUTH_CANCELED]` marker in the thrown error message to detect cancellations.
+
 ## Imperative API
 
 ```tsx

SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| --- | --- |
+| 6.x | ✅ Supported
+| 5.6.x | ✅ Supported
+| < 5.6.0 | ❌ Not supported
+
+We ship security fixes for the current v6 line and the latest v5 maintenance branch (≥ 5.6.0). Releases prior to 5.6.0 no longer receive patches—upgrade as soon as possible to stay protected.
+
+## Reporting a Vulnerability
+
+1. **Contact**: Email security reports to <mtw.andrade@gmail.com>.
+2. **Disclosure Window**: We aim to acknowledge reports within 3 business days and provide a remediation plan within 10 business days.
+3. **Coordinated Disclosure**: Please refrain from publicly disclosing the issue until a fix is available or 30 days have passed since acknowledgement.
+
+## Patch Process
+
+- Critical fixes ship in a point release for the supported branches (6.x and ≥ 5.6.0).
+- Vulnerability advisories are published on the GitHub release page and npm once patches are available.
+- We credit reporters who follow coordinated disclosure and wish to be acknowledged.
+
+## Hardening Recommendations
+
+- Stay on the latest minor release within your major version to receive defense-in-depth updates.
+- Review the [Access control & metadata](README.md#-access-control--metadata) section for guidance on choosing the strongest policies.
+- Test secure storage flows on physical hardware before shipping; emulators often omit secure elements.
+
+Thank you for helping us keep `react-native-sensitive-info` secure.