From fb9eb058f1c9b7cb26f33bbe679a85f530566641 Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 29 Mar 2026 08:37:54 +0000
Subject: furgit: Broad architecture ish docs?

---
 furgit.go | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'furgit.go')

diff --git a/furgit.go b/furgit.go
index 4f57e70d..78ec4f51 100644
--- a/furgit.go
+++ b/furgit.go
@@ -1,5 +1,18 @@
 // Package furgit provides low-level Git operations.
 //
+// Git libraries often center on a repository type that owns objects, refs,
+// worktree state, and configuration behind a single facade. Furgit inverts
+// that: objects are plain values, stored objects are separate types that
+// associate objects with their object IDs, object storage and ref storage
+// are sets of narrow interfaces consisting only of things that are truly
+// reasonable for all implementations to satisfy, and every higher-level
+// operation, such as commit traversal, reachability analysis, and
+// recursive peeling, is built over those interfaces.
+//
+// While the [repository] package is where most users should begin, it only
+// exists as one convenient composition of those pieces for the standard
+// on-disk repository layout. Nothing should depend on it.
+//
 // # Contract labels
 //
 // Many furgit APIs document concurrency, dependency ownership, value lifetime,
-- 
cgit v1.3.1-10-gc9f91