epiq 1.6.1 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "epiq",
-	"version": "1.6.1",
+	"version": "1.7.2",
 	"license": "MIT",
 	"type": "module",
 	"description": "EPIQ - ergonomic, distributed CLI-first issue tracker TUI ready for the agentic era",
@@ -46,14 +46,14 @@
 		"test:e2e:ci": "export IS_CI=true && ([ -n \"${EPIQ_SKIP_BUILD:-}\" ] || npm run build:npm) && vitest run source/test/e2e/",
 		"test:e2e": "docker run --rm -e EPIQ_SKIP_BUILD -v \"$PWD\":/app -v /app/node_modules -w /app epiq-e2e npm run test:e2e:ci",
 		"test:gui": "playwright test",
-		"test:gui:ci": "npm run build:npm && playwright install --no-shell chromium && playwright test",
+		"test:gui:ci": "export IS_CI=true && npm run build:npm && playwright install --with-deps chromium && playwright test",
 		"build:e2e:image": "docker build -f source/test/e2e/Dockerfile -t epiq-e2e .",
 		"prepack": "npm run build:publish",
 		"pack:check": "rm -f epiq-*.tgz && npm pack && FILE=$(ls -t epiq-*.tgz | head -n 1) && echo \"$FILE\" && tar -tf \"$FILE\"",
 		"publish:dry": "rm -f epiq-*.tgz && npm pack && FILE=$(ls -t epiq-*.tgz | head -n 1) && npm publish --dry-run \"$FILE\"",
 		"publish:tarball": "FILE=$(ls -t epiq-*.tgz | head -n 1) && echo \"Publishing $FILE\" && npm publish \"$FILE\"",
 		"release": "npm run pack:check && npm run publish:tarball",
-		"start:mcp": "IS_LOCAL=true tsx source/mcp/server.ts",
+		"start:mcp": "IS_LOCAL=true tsx source/mcp/index.ts",
 		"inspect:mcp": "npx @modelcontextprotocol/inspector",
 		"lint": "eslint .",
 		"lint:err": "eslint . --quiet",

package/readme.md

@@ -10,16 +10,36 @@ Epiq provides issue tracking as a portable, integrated part of the development e
 
 With great attention to user ergonomics and developer experience, epiq strives to make project management painless and friction free.
 
-![Epiq board with the time travel timeline](https://raw.githubusercontent.com/ljtn/epiq/main/source/assets/time-travel.png)
+![Epiq board with the time travel timeline above it](https://raw.githubusercontent.com/ljtn/epiq/main/source/assets/time-travel.jpeg)
 
 ## Audit the workflow
 
 Agents now run whole sprints unattended. Because state is a full event log, you can replay the board to find out what moved when, who moved it, and what changed along the way.
 
+## Code, linked to tickets
+
+Prefix a commit's subject with the ticket's ref and the two are linked:
+
+```
+git commit -m "1YRTG8T document the commit-to-ticket link in the readme"
+```
+
+That commit now shows up in the ticket's **Commits** tab with its diffstat, and expands into a per-file diff right inside the ticket. Drag across diff lines to quote them into a comment on the ticket, or file a new ticket straight from the selection — the quote links back to the exact lines. The scrubber plots commits alongside board events; click a commit dot to open its diff in the ticket it belongs to.
+
+![A ticket's Commits tab, showing the diff of a linked commit](https://raw.githubusercontent.com/ljtn/epiq/main/source/assets/code-diff.jpeg)
+
+The link is nothing more than the commit subject: Epiq matches commits whose subject starts with `<REF> ` (case-insensitive) and stores nothing else. That makes it robust — no hooks, no database — but it means your merge strategy has to keep those subjects on the branch you inspect:
+
+- **Prefix every commit** with the ref of the ticket it belongs to. Agents get it from the `ref` field on `epiq_issue_list` and `epiq_board_list` responses.
+- **Rebase-merge** (`gh pr merge --rebase`) so the ref-prefixed commits land on `main` as they are. A merge commit adds a subject carrying no ref; a squash merge folds every commit into one whose subject GitHub invents from the PR title, and the link is gone.
+- Squashing _within_ one ticket's commits is fine as long as the result keeps the prefix. Never squash commits carrying different refs into one.
+
 ## Terminal + Browser
 
 Epiq originated from the command line and offers a first-class terminal experience, but also features a browser interface powered by the same Git-backed event engine.
 
+![The Epiq terminal UI: the same board rendered in a terminal, with the command palette along the bottom](https://raw.githubusercontent.com/ljtn/epiq/main/source/assets/tui.jpeg)
+
 ## What is epiq?
 
 Epiq is a self hosted, vim-inspired issue tracker that brings developer experience to project management. It renders either as ASCII, or as a web GUI, and persists state as an immutable distributed event log, versioned and synchronized through Git.
@@ -44,6 +64,7 @@ These design choices result in a system that is:
 - Ergonomics — fast keyboard-driven UX, command line with history, syntax highlighting etc.
 - Command palette — press `?` to open a scrollable overview of all available commands and descriptions
 - Time travel — inspect the board as it was 1h, 1 week or 1 year ago, or replay its history as an animation
+- Linked commits — prefix commits with a ticket ref to browse their diffs from the ticket, quote lines into comments, and see them on the timeline
 - Filtering — query issues by description, tags, assignees, etc.
 - Autocompletion — minimize typing, stay in flow, reuse previous commands
 - Multi-user — collaborative synchronization via Git
@@ -196,7 +217,28 @@ Find skill at `.claude/skills/epiq/SKILL.md` that documents a recommended workfl
 
 ### Agent identity
 
-Every process — your TUI, your GUI, each agent's MCP server — writes as the user in `~/.epiq-global/config.json`, so by default the board cannot tell one agent from another. Give an agent its own identity with `EPIQ_USER_NAME`:
+Every process — your TUI, your GUI, each agent's MCP server — writes as the user in `~/.epiq-global/config.json`, so by default the board cannot tell one agent from another. Name an agent's server and it gets its own identity:
+
+```bash
+claude mcp add --scope user epiq -- npx -y -p epiq epiq-mcp claude
+```
+
+Or, in a hand-written config, as the argument after the command:
+
+```json
+{
+	"mcpServers": {
+		"epiq": {
+			"command": "npx",
+			"args": ["-y", "-p", "epiq", "epiq-mcp", "claude"]
+		}
+	}
+}
+```
+
+That agent then shows up in the contributor list, assigns itself rather than you, and authors its own events. The id is derived from the name, so one name is one contributor on every machine — reuse names instead of inventing one per session, or the registry fills with single-run identities. Naming yourself changes nothing.
+
+`EPIQ_USER_NAME` does the same thing through the environment, for a client whose config sets variables more readily than arguments:
 
 ```json
 {
@@ -210,7 +252,14 @@ Every process — your TUI, your GUI, each agent's MCP server — writes as the
 }
 ```
 
-That agent then shows up in the contributor list, assigns itself rather than you, and authors its own events. The id is derived from the name, so one name is one contributor on every machine — reuse names instead of inventing one per session, or the registry fills with single-run identities. `EPIQ_USER_ID` pins the id explicitly (26 characters of Crockford base32) if you would rather choose it. Naming yourself changes nothing.
+Setting both is an error unless they agree, rather than one quietly winning. `EPIQ_USER_ID` pins the id explicitly (26 characters of Crockford base32) if you would rather choose it, and stays environment-only.
+
+The TUI and GUI take the same name as `--as`, since their first argument is already the command:
+
+```bash
+epiq --as claude
+epiq gui --as claude
+```
 
 ### Other MCP clients