epiq 0.3.1 → 0.3.4

package/package.json

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

package/readme.md

@@ -2,6 +2,8 @@
 
 # Epiq
 
+_Distributed CLI based issue tracker TUI_ backed by git.
+
 Issue tracking is a part of the development lifecycle, but it often becomes a painful context switching exercise with poor ergonomics. `Epiq` provides issue tracking as a portable, integrated part of the development environment, with access to all the powerful tooling developers are used to. Epiq is a **CLI-native issue tracker** — powered by Git in which you can manage all your projects directly via the command line in a visual kanban board and edit content in your favorite, personalized editor.
 
 With great attention to user ergonomics, epiq intends to make project management painless and friction free again, and has developer satisfaction as its primary target.
@@ -22,8 +24,8 @@ Epiq is a vim-inspired issue tracker fully integrated in the terminal that bring
 
 Epiq renders your issue board directly in the terminal using ASCII and stores its state as an event log, versioned and synchronized through Git.
 
-![Epiq cli kanban view](./resources/overview.png)
-![Epiq cli log view](./resources/log.png)
+![Epiq cli kanban view](https://raw.githubusercontent.com/ljtn/epiq/main/resources/overview.png)
+![Epiq cli log view](https://raw.githubusercontent.com/ljtn/epiq/main/resources/log.png)
 
 ## Features
 
@@ -157,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
@@ -171,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
 
 ---