chore: update markdowns

Author: edvincandon

ARCHITECTURE.md

@@ -10,7 +10,7 @@ Internals, API, and advanced patterns. For quick start, see [README.md](./README
 - [Sanitization](#sanitization)
 - [Data Flow](#data-flow)
 - [Custom Handlers](#custom-handlers)
-- [TRAILING Mode](#trailing-mode)
+- [Transition Modes](#transition-modes)
 - [Async Patterns](#async-patterns)
 - [API Reference](#api-reference)
 
@@ -192,19 +192,23 @@ For shapes not covered by the built-ins, implement `StateHandler` directly.
 
 ---
 
-## TRAILING Mode
+## Transition Modes
 
-`DedupeMode.TRAILING` — undo-on-failure for destructive ops:
+`TransitionMode` controls re-staging and failure behavior per action type:
 
-```typescript
-const crud = crudPrepare<Todo>('id');
-const deleteTodo = createTransitions('todos::delete', DedupeMode.TRAILING)(crud.remove);
+| Mode | On re-stage | On fail | Use case |
+|------|-------------|---------|----------|
+| `DEFAULT` | Overwrite | Flag as failed | Edits |
+| `DISPOSABLE` | Overwrite | Drop transition | Creates |
+| `REVERTIBLE` | Store trailing | Stash (revert) | Deletes |
 
-dispatch(deleteTodo.stage(id));   // gone from UI (transitionId auto-detected)
-dispatch(deleteTodo.stash(id));   // back — restored from trailing
+```typescript
+const createTodo  = createTransitions('todos::add', TransitionMode.DISPOSABLE)(crud.create);
+const editTodo    = createTransitions('todos::edit')(crud.update);
+const deleteTodo  = createTransitions('todos::delete', TransitionMode.REVERTIBLE)(crud.remove);
 ```
 
-Replaced transitions are stored as fallback. `stash` restores instead of dropping.
+`REVERTIBLE` stores the replaced transition as a trailing fallback. On fail or explicit stash, the previous transition is restored.
 
 ---
 
@@ -312,7 +316,11 @@ const crud = crudPrepare<ProjectTodo>()(['projectId', 'id']);
 // crud.remove(projectId, id) → { payload: { path }, transitionId: "projectId/id" }
 ```
 
-### `createTransitions(type, dedupe?)(prepare)`
+### `retryTransition(action)`
+
+Strips `failed` and `conflict` flags from a `StagedAction`, returning a clean action ready for re-dispatch.
+
+### `createTransitions(type, mode?)(prepare)`
 
 Creates `.stage`, `.amend`, `.commit`, `.fail`, `.stash`, `.match`.
 
@@ -335,6 +343,8 @@ createTransitions('todos::add')({
 | `selectFailedTransition(id)` | `StagedAction \| undefined` |
 | `selectConflictingTransition(id)` | `StagedAction \| undefined` |
 | `selectFailedTransitions` | `StagedAction[]` |
+| `selectAllFailedTransitions(...states)` | `StagedAction[]` — aggregated across slices |
+| `selectRetryCount(id)` | `number` — retry count (0 if none) |
 
 ### State Handler Factories
 
@@ -349,6 +359,6 @@ createTransitions('todos::add')({
 
 ```typescript
 Operation.STAGE | .AMEND | .COMMIT | .STASH | .FAIL
-DedupeMode.OVERWRITE | .TRAILING
+TransitionMode.DEFAULT | .DISPOSABLE | .REVERTIBLE
 OptimisticMergeResult.SKIP | .CONFLICT
 ```

README.md

@@ -50,14 +50,14 @@ No `isLoading`, `error`, `isOptimistic` flags. A pending transition means loadin
 
 ```typescript
 import { configureStore, createSelector } from '@reduxjs/toolkit';
-import { optimistron, createTransitions, crudPrepare, recordState } from '@lostsolution/optimistron';
+import { optimistron, createTransitions, crudPrepare, recordState, TransitionMode } from '@lostsolution/optimistron';
 
 type Todo = { id: string; value: string; done: boolean; revision: number };
 
 const crud = crudPrepare<Todo>('id');
-const createTodo = createTransitions('todos::add')(crud.create);
+const createTodo = createTransitions('todos::add', TransitionMode.DISPOSABLE)(crud.create);
 const editTodo = createTransitions('todos::edit')(crud.update);
-const deleteTodo = createTransitions('todos::delete')(crud.remove);
+const deleteTodo = createTransitions('todos::delete', TransitionMode.REVERTIBLE)(crud.remove);
 
 const { reducer: todos, selectOptimistic } = optimistron(
     'todos',
@@ -225,13 +225,103 @@ All three modes are fully backwards compatible. The CRUD map only requires `{ ma
 
 ---
 
+## Selectors
+
+### `selectOptimistic`
+
+Returned from `optimistron()`. Replays pending transitions onto committed state at read-time. Wrap with `createSelector` for memoization:
+
+```typescript
+import { createSelector } from '@reduxjs/toolkit';
+
+const selectTodos = createSelector(
+    (state: RootState) => state.todos,
+    selectOptimistic((todos) => Object.values(todos.state)),
+);
+```
+
+### Per-entity status
+
+All transition selectors take a `transitionId` and a `TransitionState` — no global store shape required:
+
+```typescript
+import {
+    selectIsOptimistic,
+    selectIsFailed,
+    selectIsConflicting,
+    selectFailedTransition,
+    selectConflictingTransition,
+    selectRetryCount,
+} from '@lostsolution/optimistron';
+
+selectIsOptimistic(id)(state.todos)          // true if transition is pending
+selectIsFailed(id)(state.todos)              // true if transition has failed
+selectIsConflicting(id)(state.todos)         // true if transition conflicts with committed state
+
+selectFailedTransition(id)(state.todos)      // StagedAction | undefined
+selectConflictingTransition(id)(state.todos) // StagedAction | undefined
+selectRetryCount(id)(state.todos)            // number of times this transition was re-staged after failure
+```
+
+### Aggregate selectors
+
+```typescript
+import { selectFailedTransitions, selectAllFailedTransitions } from '@lostsolution/optimistron';
+
+selectFailedTransitions(state.todos)                                // all failed in one slice
+selectAllFailedTransitions(state.todos, state.projects, state.activity) // all failed across slices
+```
+
+---
+
+## Transition Modes
+
+`TransitionMode` controls re-staging and failure behavior per action type — declared at the `createTransitions` site:
+
+```typescript
+import { createTransitions, TransitionMode } from '@lostsolution/optimistron';
+
+const createTodo  = createTransitions('todos::add', TransitionMode.DISPOSABLE)(crud.create);
+const editTodo    = createTransitions('todos::edit')(crud.update);  // DEFAULT
+const deleteTodo  = createTransitions('todos::delete', TransitionMode.REVERTIBLE)(crud.remove);
+```
+
+| Mode | On re-stage | On fail | Use case |
+|------|-------------|---------|----------|
+| **`DEFAULT`** | Overwrite | Flag as failed | Edits — consumer retries manually |
+| **`DISPOSABLE`** | Overwrite | Drop transition | Creates — entity never existed server-side |
+| **`REVERTIBLE`** | Store trailing | Stash (revert to trailing) | Deletes — undo on failure |
+
+### Retry
+
+Retry is a consumer concern — timing, backoff, and reconnect logic belong in your app layer. The library provides the building blocks:
+
+```typescript
+import { retryTransition, selectFailedTransition, selectRetryCount } from '@lostsolution/optimistron';
+
+const failed = selectFailedTransition(id)(state.todos);
+if (failed) {
+    const retries = selectRetryCount(id)(state.todos);
+    if (retries < 3) dispatch(retryTransition(failed));  // strips failure flags, re-stages
+}
+```
+
+### Multi-slice failure aggregation
+
+```typescript
+import { selectAllFailedTransitions } from '@lostsolution/optimistron';
+
+const allFailed = selectAllFailedTransitions(state.todos, state.projects, state.activity);
+```
+
+---
+
 ## Roadmap
 
 - **Batch transitions** — stage multiple entities under a single correlation ID. Commit/fail/stash the batch atomically.
-- **Retry strategies** — configurable retry policies for failed transitions (exponential backoff, max attempts) built into the transition lifecycle.
 - **Devtools integration** — Redux DevTools timeline visualization for transitions, sanitization events, and conflict detection.
 - **Persistence adapters** — serialize/rehydrate pending transitions across page reloads (localStorage, IndexedDB).
-- **Middleware hooks** — `onConflict`, `onStale`, `onSanitize` callbacks for custom side-effects without reducer coupling.
+- **Transition expiry / TTL** — automatic cleanup of stale failed transitions after a configurable time window.
 
 ---