diff --git a/README.md b/README.md
index 8fc79ba..c768f66 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,11 @@
 # git-testkit
 
+[![CI](https://github.com/git-fire/git-testkit/actions/workflows/ci.yml/badge.svg)](https://github.com/git-fire/git-testkit/actions/workflows/ci.yml)
+[![Go Reference](https://pkg.go.dev/badge/github.com/git-fire/git-testkit.svg)](https://pkg.go.dev/github.com/git-fire/git-testkit)
+[![Go 1.22+](https://img.shields.io/badge/go-1.22+-blue.svg)](https://golang.org/dl/)
+[![Latest Release](https://img.shields.io/github/v/release/git-fire/git-testkit)](https://github.com/git-fire/git-testkit/releases/latest)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
 `git-testkit` provides helpers for writing Go tests that exercise real Git repositories.
 
 ## Why use this
@@ -113,6 +119,10 @@ func TestUsingSnapshot(t *testing.T) {
 - Helpers fail tests immediately (`t.Fatalf`) when git commands fail, so errors surface close to setup code.
 - When tests build large repo graphs repeatedly, prefer snapshot/restore to reduce total runtime.
 
+## Origin
+
+`git-testkit` was extracted from [git-fire](https://github.com/git-fire/git-fire) before its public launch and published as a standalone Go library. The test helpers had accumulated enough utility to be useful on their own, so they were split out to let other projects automate real Git repositories without depending on git-fire itself.
+
 ## Developer docs
 
 - See `DEVELOPER_GUIDE.md` for:
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..d122c17
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,29 @@
+// Package testutil provides helpers for writing Go tests that exercise real
+// Git repositories. Instead of mocking git command output, tests create actual
+// repositories on disk, apply operations through fluent builders, and assert
+// against real git state.
+//
+// The three main entry points are:
+//
+//   - [CreateTestRepo] for quickly spinning up a single repository with files,
+//     branches, and remotes already configured.
+//   - [NewScenario] for building multi-repository topologies (local + bare
+//     remote, diverged clones, worktrees, conflict states).
+//   - [SnapshotRepo] / [RestoreSnapshot] for capturing expensive fixture state
+//     once and restoring it cheaply across subtests.
+//
+// All helpers integrate with Go's testing.T: repositories are created inside
+// t.TempDir() and cleaned up automatically, and setup failures call t.Fatalf
+// so errors surface close to the fixture code rather than deep in assertions.
+//
+// # Quickstart
+//
+//	func TestMyFeature(t *testing.T) {
+//		repoPath := testutil.CreateTestRepo(t, testutil.RepoOptions{Name: "subject"})
+//		testutil.RunGitCmd(t, repoPath, "checkout", "-b", "feature")
+//		// exercise your code against repoPath
+//		if testutil.IsDirty(t, repoPath) {
+//			t.Fatal("expected clean repo")
+//		}
+//	}
+package testutil