17 files changed, 23 insertions, 16 deletions
diff --git a/STRUCTURE b/STRUCTURE
index ab848956..25052146 100644
--- a/STRUCTURE
+++ b/STRUCTURE
@@ -1,7 +1,7 @@
 .
 ├── config         Configuration parsing
 ├── internal       Private packages and helpers
-│   ├── cache
+│   ├── cache      Encapsulates cache-providing subpackages for direct use
 │   │   └── lru    Size-cost bounded LRU cache (e.g., for delta base caching)
 │   └── testgit    Helpers for integration tests with upstream git(1)
 ├── object         Parse/serialize objects such as blob, tree, commit, tag
diff --git a/config/config.go b/config/config.go
index 1344c890..d5e143aa 100644
--- a/config/config.go
+++ b/config/config.go
@@ -1,4 +1,4 @@
-// Package config provides routines to parse Git configuration files.
+// Package config provides configuration parsing.
 package config
 
 import (
diff --git a/internal/cache/cache.go b/internal/cache/cache.go
new file mode 100644
index 00000000..17633906
--- /dev/null
+++ b/internal/cache/cache.go
@@ -0,0 +1,2 @@
+// Package cache encapsulates cache-providing subpackages for direct use.
+package cache
diff --git a/internal/cache/lru/lru.go b/internal/cache/lru/lru.go
index b1ba0ed3..fd080bbd 100644
--- a/internal/cache/lru/lru.go
+++ b/internal/cache/lru/lru.go
@@ -1,4 +1,4 @@
-// Package lru provides a weighted least-recently-used cache.
+// Package lru provides a size-cost bounded LRU cache.
 package lru
 
 import "container/list"
diff --git a/internal/internal.go b/internal/internal.go
new file mode 100644
index 00000000..9c785745
--- /dev/null
+++ b/internal/internal.go
@@ -0,0 +1,3 @@
+// Package internal provides private packages and helpers.
+package internal
+
diff --git a/object/object.go b/object/object.go
index b91fd324..9a402336 100644
--- a/object/object.go
+++ b/object/object.go
@@ -1,4 +1,5 @@
-// Package object provides Git object models and codecs.
+// Package object parses and serializes objects such as blob, tree, commit, and
+// tag.
 package object
 
 import "codeberg.org/lindenii/furgit/objecttype"
diff --git a/objectid/objectid.go b/objectid/objectid.go
index a2fa28c4..da4b7a3a 100644
--- a/objectid/objectid.go
+++ b/objectid/objectid.go
@@ -1,4 +1,4 @@
-// Package objectid provides object ID and algorithm primitives for Git objects.
+// Package objectid provides utilities around object IDs and hash algorithms.
 package objectid
 
 import (
diff --git a/objectstore/chain/chain.go b/objectstore/chain/chain.go
index 2f90d822..3d683c0d 100644
--- a/objectstore/chain/chain.go
+++ b/objectstore/chain/chain.go
@@ -1,4 +1,5 @@
-// Package chain provides an ordered object database chain implementation.
+// Package chain provides a wrapper object storage backend to query a chain of
+// backends.
 package chain
 
 import (
diff --git a/objectstore/loose/store.go b/objectstore/loose/store.go
index b06d8a78..b0f64971 100644
--- a/objectstore/loose/store.go
+++ b/objectstore/loose/store.go
@@ -1,4 +1,4 @@
-// Package loose provides loose-object reads from a Git objects directory.
+// Package loose provides a loose object backend (objects/XX/YYYYY..).
 package loose
 
 import (
diff --git a/objectstore/objectstore.go b/objectstore/objectstore.go
index 54760709..def71c85 100644
--- a/objectstore/objectstore.go
+++ b/objectstore/objectstore.go
@@ -1,4 +1,4 @@
-// Package objectstore provides storage interfaces for Git objects.
+// Package objectstore provides interfaces for object storage backends.
 package objectstore
 
 import (
diff --git a/objectstore/packed/store.go b/objectstore/packed/store.go
index d780245d..fc2e1c10 100644
--- a/objectstore/packed/store.go
+++ b/objectstore/packed/store.go
@@ -1,4 +1,4 @@
-// Package packed provides read access to packed Git objects from objects/pack.
+// Package packed provides packfile reading and associated indexes.
 package packed
 
 import (
diff --git a/objecttype/objecttype.go b/objecttype/objecttype.go
index dcf3ca03..d9199509 100644
--- a/objecttype/objecttype.go
+++ b/objecttype/objecttype.go
@@ -1,4 +1,4 @@
-// Package objecttype defines Git object type identifiers.
+// Package objecttype provides object type constants and names.
 package objecttype
 
 // Type mirrors Git object type tags in packfiles.
diff --git a/ref/ref.go b/ref/ref.go
index 28b90ae6..3752d1e3 100644
--- a/ref/ref.go
+++ b/ref/ref.go
@@ -1,4 +1,4 @@
-// Package ref provides Git reference models.
+// Package ref provides general, detached, and symbolic references.
 package ref
 
 import "codeberg.org/lindenii/furgit/objectid"
diff --git a/refstore/chain/chain.go b/refstore/chain/chain.go
index 0a78dc94..633bac25 100644
--- a/refstore/chain/chain.go
+++ b/refstore/chain/chain.go
@@ -1,4 +1,5 @@
-// Package chain provides an ordered reference store chain implementation.
+// Package chain provides a wrapper reference storage backend to query a chain
+// of backends.
 package chain
 
 import (
diff --git a/refstore/loose/store.go b/refstore/loose/store.go
index 4102ea0d..8eb485e9 100644
--- a/refstore/loose/store.go
+++ b/refstore/loose/store.go
@@ -1,4 +1,4 @@
-// Package loose provides read access to loose Git references.
+// Package loose provides a loose ref backend (refs/... as a directory tree).
 package loose
 
 import (
diff --git a/refstore/packed/store.go b/refstore/packed/store.go
index 377eb75c..d792e738 100644
--- a/refstore/packed/store.go
+++ b/refstore/packed/store.go
@@ -1,4 +1,4 @@
-// Package packed provides read access to packed Git references.
+// Package packed provides a packed refs backend.
 package packed
 
 import (
diff --git a/refstore/reftable/store.go b/refstore/reftable/store.go
index df874c69..ac730a4b 100644
--- a/refstore/reftable/store.go
+++ b/refstore/reftable/store.go
@@ -1,5 +1,4 @@
-// Package reftable provides read access to Git reftable reference storage.
-// This store is experimental, has many issues, and should not be used in any serious capacity for now.
+// Package reftable provides an experimental reftable backend.
 package reftable
 
 import (