epiq 0.3.2 → 0.3.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "epiq",
-	"version": "0.3.2",
-	"license": "UNLICENSED",
+	"version": "0.3.4",
+	"license": "MIT",
 	"type": "module",
 	"description": "EPIQ - CLI based issue tracker",
 	"keywords": [

package/readme.md

@@ -159,9 +159,6 @@ Clear all filters with `:filter clear`
 
 - Pro tip: just like in any terminal - if you need to do repeating tasks over and over again, you can just put yourself in the command mode, and then press arrow up, in order to access the last executed command. This helps a lot when you create tasks with similar names, or add the same tag to many tickets and so on.
 
-Starting the application will launch a wizard that sets you up in 20 seconds.
-It will result in settings persisted at `~/.epicrc`
-
 ---
 
 ## How epiq is synchronized
@@ -173,7 +170,46 @@ Epiq uses Git in the background to synchronize state between clients. No manual
 
 The `.epiq/` folder is non-authoritative and used for caching and local tracking. It can optionally be committed if you want your board state versioned alongside your code.
 
-> The system is designed to assure robustness and uses a number of techniques and design patterns to avoid merge conflicts.
+## Conflict Avoidance & Data Integrity
+
+Epiq is designed to provide robustness in a distributed, Git-backed environment where multiple users may update state concurrently. Instead of mutating shared files, Epiq uses an event-sourced model to minimize merge conflicts and make concurrent changes predictable.
+
+### Event-sourced state
+
+All changes are stored as **append-only events** in user-scoped files, rather than modifying a shared state file. This avoids in-place edits to the same lines and significantly reduces the likelihood of Git conflicts.
+
+State is reconstructed in-memory by replaying a merge of all user logs.
+
+### Deterministic materialization
+
+The current state is derived by replaying events in a deterministic order.
+
+Events use a composite of time-sortable IDs (ULIDs) and a reference to the last known event ("edge"). On creation, events are appended relative to the last known event. If multiple events share the same reference point, their relative order is resolved using their time-based IDs.
+
+This approach:
+
+- Provides stable and reproducible ordering across machines
+- Limits the impact of potential clock drift to small local ordering differences
+- Ensures that concurrent updates converge to the same state
+
+### Conflict handling model
+
+Epiq resolves concurrent changes at the event level:
+
+- Events are designed to be **idempotent** where possible
+- Later events take precedence when conflicts occur
+
+Because events are append-only and scoped to 1 file per user, Git merges become trivial combinations of changes in independent files.
+
+### Local-first with eventual consistency
+
+Epiq follows a **local-first** model:
+
+- All operations apply instantly on the local machine
+- Synchronization happens explicitly (`:sync`) or automatically
+- When histories diverge, merging event logs and replaying them leads to a consistent state
+
+> Frequent synchronization reduces divergence and keeps the system predictable
 
 ---