repository: Add guidance

8 files changed, 36 insertions, 9 deletions

diff --git a/repository/commit_graph.go b/repository/commit_graph.go
index 3f0a0888..4f210b56 100644
--- a/repository/commit_graph.go
+++ b/repository/commit_graph.go
@@ -31,6 +31,11 @@ func openCommitGraph(root *os.Root, algo objectid.Algorithm) (*commitgraphread.R
 
 // CommitGraph returns the configured commit-graph reader, if available.
 //
+// Not all repositories have a commit-graph, so CommitGraph may return nil.
+// Most callers should prefer [Repository.CommitQueries] or
+// [Repository.Reachability] unless they specifically need direct
+// commit-graph access.
+//
 // Labels: Life-Parent, Close-No.
 func (repo *Repository) CommitGraph() *commitgraphread.Reader {
 	return repo.commitGraph
diff --git a/repository/commit_queries.go b/repository/commit_queries.go
index e3d223ae..1377fd96 100644
--- a/repository/commit_queries.go
+++ b/repository/commit_queries.go
@@ -5,6 +5,8 @@ import "codeberg.org/lindenii/furgit/commitquery"
 // CommitQueries returns commit queries backed by the repository's object store
 // and optional commit-graph.
 //
+// Use CommitQueries for ancestor checks and merge-base computation.
+//
 // Labels: Life-Parent, Close-No.
 func (repo *Repository) CommitQueries() *commitquery.Queries {
 	return repo.commitQueries
diff --git a/repository/fetcher.go b/repository/fetcher.go
index 6701b806..7c3ea421 100644
--- a/repository/fetcher.go
+++ b/repository/fetcher.go
@@ -4,6 +4,10 @@ import "codeberg.org/lindenii/furgit/object/fetch"
 
 // Fetcher returns an object fetcher backed by the repository's object store.
 //
+// Use Fetcher when you want typed commits, trees, blobs, or tags, when you
+// need to peel through annotated tags, or when you want path-based access
+// within trees.
+//
 // Labels: Life-Parent, Close-No.
 func (repo *Repository) Fetcher() *fetch.Fetcher {
 	return fetch.New(repo.objects)
diff --git a/repository/objects.go b/repository/objects.go
index ea1956c1..62170514 100644
--- a/repository/objects.go
+++ b/repository/objects.go
@@ -77,6 +77,10 @@ func openObjectStore(
 
 // Objects returns the configured object store.
 //
+// Use Objects for direct object-ID lookups, object headers, sizes, raw object
+// bytes, or streamed object contents. Callers who want typed object values
+// should usually prefer [Repository.Fetcher].
+//
 // Labels: Life-Parent, Close-No.
 //
 //nolint:ireturn
diff --git a/repository/open.go b/repository/open.go
index 3c400f60..3724df26 100644
--- a/repository/open.go
+++ b/repository/open.go
@@ -8,7 +8,11 @@ import (
 	reffiles "codeberg.org/lindenii/furgit/ref/store/files"
 )
 
-// Open opens a repository and wires object/ref stores from its on-disk format.
+// Open opens a repository and wires its stores and helpers from the on-disk
+// repository format.
+//
+// root must refer to the Git directory itself:
+// a bare repository root or a non-bare ".git" directory.
 //
 // Labels: Deps-Borrowed.
 func Open(root *os.Root) (repo *Repository, err error) {
diff --git a/repository/reachability.go b/repository/reachability.go
index 4e6a4559..24f9e2bd 100644
--- a/repository/reachability.go
+++ b/repository/reachability.go
@@ -5,6 +5,9 @@ import "codeberg.org/lindenii/furgit/reachability"
 // Reachability returns graph traversal helpers backed by the repository's
 // object store and optional commit-graph.
 //
+// Use Reachability to walk reachable commits or objects and to perform
+// connectivity checks.
+//
 // Labels: Life-Parent, Close-No.
 func (repo *Repository) Reachability() *reachability.Reachability {
 	return reachability.New(repo.objects, repo.commitGraph)
diff --git a/repository/refs.go b/repository/refs.go
index 2e89aed6..0403e001 100644
--- a/repository/refs.go
+++ b/repository/refs.go
@@ -4,6 +4,10 @@ import refstore "codeberg.org/lindenii/furgit/ref/store"
 
 // Refs returns the configured ref store.
 //
+// Use Refs when starting from branch names, tags, HEAD, or other references.
+// A common pattern is to resolve a reference first and then pass the resulting
+// object ID to [Repository.Fetcher] or [Repository.Objects].
+//
 // Labels: Life-Parent, Close-No.
 //
 //nolint:ireturn
diff --git a/repository/repository.go b/repository/repository.go
index 119f8c42..301607f9 100644
--- a/repository/repository.go
+++ b/repository/repository.go
@@ -1,4 +1,10 @@
-// Package repository opens stores and other objects to access a typical on-disk repo.
+// Package repository opens a typical on-disk Git repository and exposes its
+// main stores and helpers.
+//
+// Start with [Open] when working with a bare repository root or a non-bare
+// ".git" directory. [Repository] then provides access to ref storage, object
+// storage, typed object fetching, commit queries, reachability helpers, and
+// optional commit-graph access.
 package repository
 
 import (
@@ -14,17 +20,12 @@ import (
 	refstore "codeberg.org/lindenii/furgit/ref/store"
 )
 
-// Repository represents a typical on-disk Git repository by composing
-// its stores together for access.
+// Repository represents a typical on-disk Git repository by composing its
+// stores and helpers together for access.
 //
 // Open expects a root for the Git directory itself:
 // a bare repository root or a non-bare ".git" directory.
 //
-// Accessors such as [Repository.Objects], [Repository.CommitGraph],
-// [Repository.CommitQueries], [Repository.Reachability], [Repository.Refs],
-// [Repository.Fetcher], and [Repository.LooseStoreForWriting] return
-// repository-backed views.
-//
 // Labels: MT-Safe, Close-Caller.
 type Repository struct {
 	config *config.Config