docs: update README and CONTRIBUTING guidelines for clarity

- Expanded peer dependency details in README (including @types/react-dom).
- Updated descriptions for `watch()` callbacks and `getAll()` behavior.
- Clarified SecureStorage key formatting for namespaced storage.
- Improved MonoStorage `watch()` explanation with deep comparison info.
- Revised CONTRIBUTING.md to align with a Simplified GitFlow model.
- Removed references to `release/*` and `hotfix/*` branches in release process.

Author: Addon Stack

CONTRIBUTING.md

@@ -12,7 +12,7 @@ Please also read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md).
 
 ## Table of contents
 - Principles and workflow
-- Git branching model (GitFlow)
+- Git branching model (Simplified GitFlow)
 - Commit messages (Conventional Commits)
 - What affects versioning (SemVer policy)
 - Release process (release-it + GitHub Actions)
@@ -26,26 +26,22 @@ Please also read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md).
 
 ## Principles and workflow
 We value clarity, automation, and a predictable release cadence. We use:
-- GitFlow for branching and release discipline.
+- Simplified GitFlow (no release/* or hotfix/* branches) for branching and release discipline.
 - Conventional Commits to generate CHANGELOG and calculate version bumps.
 - release-it to cut releases and publish to npm and GitHub.
 - Biome for formatting and linting; Jest for tests.
 
-## Git branching model (GitFlow)
-We follow a pragmatic GitFlow variant:
-- `main` — production-ready branch. Commits here trigger a publish release.
-- `develop` — integration branch for upcoming work (default target for feature PRs).
+## Git branching model (Simplified GitFlow)
+We follow a simplified GitFlow:
+- `main` — production-ready branch. Merging a PR into `main` triggers a publish release.
+- `develop` — integration branch for upcoming work (default target for feature PRs). After each successful release, we merge `main` back into `develop` to keep versions and files in sync.
 - `feature/*` — feature branches cut from `develop`. Example: `feature/secure-storage-iv`.
-- `release/*` — release preparation branches cut from `develop`. Example: `release/0.4.0`.
-- `hotfix/*` — urgent fixes cut from `main`. Example: `hotfix/deserialize-crash`.
 
 Typical flows:
 - New work: branch from `develop` into `feature/<name>`, open PR into `develop`.
-- Release: maintainers create `release/x.y.z` from `develop`, stabilize, then merge to `main`.
-- Hotfix: branch from `main` into `hotfix/<name>`, then merge back to `main` (and forward-merge into `develop`).
+- Release: open a pull request from the chosen base branch (typically `develop`) into `main`. After merge, CI publishes a new version and npm package. Then merge `main` back into `develop` to sync.
 
-Note: Our CI includes a release preview for `release/*` and `hotfix/*` branches and performs a publish release on
-`main`.
+Note: We do not use `release/*` or `hotfix/*` branches.
 
 ## Commit messages (Conventional Commits)
 We enforce Conventional Commits via commitlint. The general format is:
@@ -75,7 +71,7 @@ Examples:
 - `fix(secure): handle invalid cipher text in decrypt()`
 - `perf(mono): reduce allocations in shallowEqual()`
 - `docs: expand README with React adapter examples`
-- `ci: run release preview on release/* branches`
+- `ci: update release pipeline`
 
 Breaking changes:
 - Indicate with `!` after the type or include a `BREAKING CHANGE:` footer.
@@ -99,10 +95,10 @@ Notes:
 ## Release process (release-it + GitHub Actions)
 We automate releases with [release-it](https://github.com/release-it/release-it) and GitHub Actions.
 
-Branches:
-- `release/*` and `hotfix/*`: CI runs a Release Preview (no tag, no publish). This validates versioning and the
+Branches/Triggers:
+- Pull requests into `main`: CI runs checks and may run a release dry-run (no tag, no publish) to validate versioning and the
   generated notes.
-- `main`: CI runs a Release Publish that will:
+- `main` (on merge): CI runs a Release Publish that will:
   - determine the next version from commits (SemVer + Conventional Commits),
   - update `CHANGELOG.md`,
   - create a Git tag `vX.Y.Z` and a GitHub Release,
@@ -114,7 +110,9 @@ Local release commands (maintainers):
 
 Important:
 - Do not manually edit `CHANGELOG.md` for released versions — it’s generated.
-- Ensure `develop` is up to date before cutting `release/*`.
+- Ensure the intended changes are in `develop` (or the chosen base branch) before opening a PR to `main`.
+- After a successful release, merge `main` back into `develop` to keep versions and files in sync.
+- We do not use `release/*` or `hotfix/*` branches.
 
 ## Code style and quality
 We use [Biome](https://biomejs.dev/) for formatting and linting. Key rules from `biome.json`:
@@ -160,7 +158,7 @@ Authoring tests:
 
 ## Pull requests
 Checklist for contributors:
-- [ ] Branch from `develop` (or `hotfix/*` from `main` for urgent fixes).
+- [ ] Branch from `develop`.
 - [ ] Follow code style and run locally:
   - `npm run format:check && npm run lint && npm run typecheck && npm test`
 - [ ] Write or update tests when applicable.

README.md

@@ -29,7 +29,7 @@ pnpm add @addon-core/storage
 Requirements and environment:
 
 - The library targets browser extension environments where chrome.storage is available.
-- For the React adapter, peer dependencies react and react-dom are required (optionally @types/react for TypeScript).
+- For the React adapter, peer dependencies react and react-dom are required (optionally @types/react and @types/react-dom for TypeScript).
 - SecureStorage relies on the Web Crypto API (crypto.subtle, AES‑GCM), available in modern browsers.
 
 ## Quick start
@@ -52,7 +52,7 @@ await storage.clear(); // clears only keys from the current namespace (if set)
 The package exports:
 
 - Provider classes: `Storage`, `SecureStorage`, `MonoStorage`
-- Types: `StorageProvider`, `StorageState`, `StorageWatchOptions`
+- Types: `StorageProvider`, `StorageState`, `StorageWatchOptions`, `StorageWatchCallback`, `StorageWatchKeyCallback`
 - React adapter: `useStorage` from the submodule `@addon-core/storage/react`
 
 ### Creating a provider
@@ -84,7 +84,7 @@ const secure = SecureStorage.Local<{ token?: string }>({secureKey: "MyStrongKey"
 Provider options:
 
 - `area?: "local" | "session" | "sync" | "managed"` — storage area (defaults to `local`)
-- `namespace?: string` — optional namespace; keys become `namespace:key`
+- `namespace?: string` — optional namespace; keys become `namespace:key` (for `SecureStorage`: `secure:namespace:key`)
 - For `SecureStorage`: additionally `secureKey?: string` — a string used to derive the encryption key.
 
 ### Provider methods
@@ -111,8 +111,8 @@ Where `StorageWatchOptions<T>` is either a map of per-key callbacks or a single
 
 ```ts
 // Option 1: a single handler for all changes
-const unsubscribe = storage.watch((next, prev) => {
-    console.log("changed", {next, prev});
+const unsubscribe = storage.watch((next, prev, key) => {
+    console.log("changed", {key, next, prev});
 });
 
 // Option 2: specific handlers per key
@@ -131,7 +131,8 @@ un(); // unsubscribe
 
 Notes:
 
-- `getAll()` returns only keys that belong to the current provider (considering namespace and type).
+- `getAll()` returns entries (key–value pairs) scoped to the current provider (area, namespace, provider kind) and resolves to `Partial<T>`.
+- In the single-callback form of `watch()`, the third argument is the `key` that changed.
 - `SecureStorage` transparently encrypts/decrypts values. They are stored as strings, while you work with original types
   externally.
 
@@ -168,7 +169,7 @@ await mono.set("a", 1);
 Highlights:
 
 - When the last value in the “bucket” is removed, the top-level key is cleared entirely.
-- `watch()` in MonoStorage invokes callbacks only on actual value changes (shallow comparison).
+- `watch()` in MonoStorage invokes callbacks only on actual value changes (deep/structural comparison).
 
 ### SecureStorage — value encryption