Documented the new UX loop, drop-in action, and demo.

README.md now walks through record ➜ timeline ➜ export, highlights the composite GitHub Action usage, and points to the flaky CI demo flow.
docs/quickstart.md updated to use the built-in flaky demo with a timeline step before export.
CHANGELOG.md and docs/releases/release-notes.md add a v2.1 entry for the timeline command, GitHub Action, and demo.

Author: Shane Wall

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v2.1 - Timeline UX + CI Action (2025-11-28)
+- New `timeline` command to list all file events with relative timestamps (no more guessing export times).
+- Added composite GitHub Action (`action.yml`) for one-line CI adoption: `uses: saworbit/diffkeeper@v1`.
+- Included flaky CI demo (`demo/flaky-ci-test`) and updated docs/readme/quickstart to show the full record ➜ timeline ➜ export loop.
+
 ## v2.0 - Time Machine Preview (2025-11-28)
 - Pivoted from BoltDB persistence to Pebble-based flight recorder with key prefixes (`l:/c:/m:`).
 - Added journal ingestion + async worker that hashes/compresses into CAS and metadata.

README.md

@@ -3,11 +3,11 @@
 [![CI](https://github.com/saworbit/diffkeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/saworbit/diffkeeper/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**DiffKeeper is a "Black Box Flight Recorder" for your containers.**
+**DiffKeeper is a Black Box Flight Recorder for your containers.**
 
-It watches your application's filesystem in real-time and records every change. When a container crashes—or a CI test flakes—you can rewind the state to any exact moment in time to see exactly what happened.
+It watches your application's filesystem in real-time and records every change. When a container crashes—or a CI test flakes—you can rewind the state to any exact moment and see exactly what happened.
 
-> **Note:** This project previously focused on "Stateful Containers" and database persistence. That architecture has been archived. See [Genesis & Pivot](docs/GENESIS_AND_PIVOT.md) for the story.
+> **Note:** The earlier "stateful containers" design is archived. See [Genesis & Pivot](docs/GENESIS_AND_PIVOT.md) for the story.
 
 ---
 
@@ -17,33 +17,67 @@ You have a flaky test in CI. It fails 1 out of 50 times. You re-run the job, and
 * They don't show you that a config file was corrupted, a temp file was locked, or a binary was overwritten.
 
 ## The Solution: Instant Replay
-DiffKeeper uses eBPF to capture filesystem writes at line-rate and stores them in a high-speed log (Pebble).
+DiffKeeper uses eBPF to capture filesystem writes at line-rate and stores them in Pebble. Then it gives you a timeline so you never guess timestamps again.
 
-### 1. Record a Session
-Wrap your flaky test (or command) with `diffkeeper record`. It adds minimal overhead.
+### 1) Record a Session
+Wrap your flaky test (or any command). Minimal overhead.
 
 ```bash
-# In your local terminal or CI pipeline
 diffkeeper record --state-dir=/tmp/trace -- go test ./...
 ```
 
-### 2. Export the "Crash Site"
-The test failed! But the container is gone. No problem—DiffKeeper saved the history. Restore the filesystem to exactly 2 minutes and 14 seconds into the run:
+### 2) See the Timeline (no blindfolds)
+List every write in order to pick the exact second to rewind:
+
+```bash
+diffkeeper timeline --state-dir=/tmp/trace
+[00m:01s] WRITE    status.log (13B)
+[00m:05s] WRITE    db.lock (6B)
+[02m:14s] WRITE    status.log (22B)   <-- the failure
+```
+
+### 3) Export the Crash Site
+Restore the filesystem to the moment of failure:
 
 ```bash
 diffkeeper export --state-dir=/tmp/trace --out=./debug_fs --time="2m14s"
 ```
 
-Now `cd ./debug_fs` and explore the files exactly as they existed at that moment.
+`cd ./debug_fs` and inspect files exactly as they existed at that moment.
+
+## Drop-in GitHub Action
+No curl | sh snippets needed—use the composite action directly:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - name: Record flaky test
+    uses: saworbit/diffkeeper@v1
+    with:
+      command: go test ./...
+      state-dir: diffkeeper-trace
+```
+
+On failure the trace uploads as an artifact; you can run `diffkeeper timeline` to find the culprit write, then `diffkeeper export` to reconstruct it locally.
+
+## The "Flaky CI" Demo
+Run the built-in demo to see the loop end-to-end:
+
+```bash
+diffkeeper record --state-dir=./trace -- go run ./demo/flaky-ci-test
+diffkeeper timeline --state-dir=./trace
+diffkeeper export --state-dir=./trace --out=./restored --time="2s"
+cat ./restored/status.log  # ERROR: Connection Lost
+```
 
 ## Architecture
 - **Engine:** Pure Go + eBPF (CO-RE)
-- **Storage:** Pebble (LSM Tree) for high-speed ingestion.
-- **Diffing:** bsdiff (Binary patches) for efficient storage.
+- **Storage:** Pebble (LSM) for high-speed ingestion.
+- **Diffing:** bsdiff (binary patches) for efficient storage.
 
 ## CI / Dogfooding
-- GitHub Actions (`.github/workflows/ci.yml`) runs unit/race tests, cross-platform builds, and a functional "time machine" test that records a flaky script and verifies exports at multiple timestamps.
-- The BoltDB era workflows are archived under `docs/archive/v1-legacy/workflows/`.
+- GitHub Actions (`.github/workflows/ci.yml`) runs unit/race tests, cross-platform builds, and a functional time-machine test that records a flaky script and verifies exports.
+- BoltDB-era workflows remain archived under `docs/archive/v1-legacy/workflows/`.
 
 ## Getting Started
-See the [Quickstart](docs/quickstart.md) to record your first trace.
+See the [Quickstart](docs/quickstart.md) to record, view the timeline, and export your first trace.

docs/quickstart.md

@@ -1,49 +1,42 @@
 # Quickstart
 
-This guide shows you how to use DiffKeeper to debug a "flaky" script.
+Debug a flaky script end-to-end: record, inspect the timeline, and rewind to the exact moment it broke.
 
-## 1. Installation
+## 1) Build DiffKeeper (or install via the GitHub Action)
 
 ```bash
-# Build from source (requires Go 1.23+)
+# Build from source (Go 1.23+)
 go build -o diffkeeper .
 ```
 
-## 2. The "Flaky" Application
-Create a script `flaky.sh` that simulates a bug where a file gets corrupted halfway through execution:
+CI users can skip this and reference `uses: saworbit/diffkeeper@v1` in a workflow.
 
-```bash
-#!/bin/bash
-echo "All systems operational" > status.txt
-sleep 2
-echo "CRITICAL FAILURE" > status.txt  # <--- The Bug
-sleep 1
-```
-
-## 3. Record the Crash
-Run the script wrapped in DiffKeeper:
+## 2) Run the Flaky Demo Under DiffKeeper
+The repo ships with a tiny flaky test that silently corrupts `status.log` after 2 seconds.
 
 ```bash
-./diffkeeper record --state-dir=./trace -- ./flaky.sh
+./diffkeeper record --state-dir=./trace -- go run ./demo/flaky-ci-test
 ```
 
-## 4. Time Travel
-Investigate what the file looked like before the crash (at 1 second) and after (at 3 seconds).
+The process exits with a failure after a few seconds (expected).
 
-**At 1 Second:**
+## 3) Read the Timeline (no more guesswork)
 
 ```bash
-./diffkeeper export --state-dir=./trace --out=./restore_1s --time="1s"
-cat ./restore_1s/status.txt
-# Output: All systems operational
+./diffkeeper timeline --state-dir=./trace
+[00m:00s] WRITE    status.log (13B)
+[00m:01s] WRITE    db.lock (6B)
+[00m:02s] WRITE    status.log (22B)   <-- corruption point
 ```
 
-**At 3 Seconds:**
+Now you know the precise timestamp to rewind to.
+
+## 4) Export the Crash Site
 
 ```bash
-./diffkeeper export --state-dir=./trace --out=./restore_3s --time="3s"
-cat ./restore_3s/status.txt
-# Output: CRITICAL FAILURE
+./diffkeeper export --state-dir=./trace --out=./restored --time="2s"
+cat ./restored/status.log
+# Output: ERROR: Connection Lost
 ```
 
-You have now successfully captured and rewound a filesystem state!
+You have successfully captured the filesystem history, located the offending write, and restored the exact failing state.

docs/releases/release-notes.md

@@ -1,5 +1,20 @@
 # DiffKeeper Release Notes
 
+## v2.1 "Timeline UX" - November 28, 2025
+
+**Status:** Preview (ready for CI adoption)
+
+### Highlights
+- **Timeline CLI:** `diffkeeper timeline` streams a chronological feed of filesystem writes with relative timestamps, so export targets are never a guess.
+- **GitHub Action:** Composite `action.yml` enables `uses: saworbit/diffkeeper@v1` with automatic artifact upload of traces on failure.
+- **Flaky Demo:** Added `demo/flaky-ci-test` and doc updates (README/quickstart) to show record ➜ timeline ➜ export in a few seconds.
+
+### Notes
+- Timeline reads Pebble metadata in read-only mode; no impact on recorded traces.
+- Action installs via release installer and runs `diffkeeper record` with sudo to attach eBPF on Linux runners.
+
+---
+
 ## v2.0 "Time Machine" - November 28, 2025
 
 **Status:** Preview (CI/CD flight recorder)