diff --git a/.gitignore b/.gitignore
index 7ebd618..0880516 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,7 +14,12 @@ dist/
 bin/
 
 # Build artifacts
+# Both patterns are anchored on purpose. A bare "codamigo" would also match the
+# cmd/codamigo source directory and hide every file added under it.
 /codamigo
+# `go build ./cmd/codamigo/` run from inside that directory, rather than the
+# `make build` target, leaves the binary here.
+/cmd/codamigo/codamigo
 /build/
 
 # Test artifacts
diff --git a/README.md b/README.md
index 2a0abbc..94e6ff0 100644
--- a/README.md
+++ b/README.md
@@ -262,7 +262,11 @@ codamigo download-model --model all-MiniLM-L6-v2
 | `--force` | Re-download files that are already present and verified |
 | `--hf-token` | HuggingFace token; only needed for gated or private models |
 
-Re-running is a no-op: files already present with a matching size and hash are skipped. A file that fails verification is deleted before the error is reported, so a retry starts clean.
+Files already present with a matching size and hash are skipped, and a file that fails verification is deleted before the error is reported, so a retry starts clean.
+
+Re-running always re-resolves the revision upstream, which is how you move a model to a newer one. For a built-in model that changes nothing — its revision is fixed. For a bare repository id it means a re-run after upstream's `main` has moved downloads the new revision in full — a fresh 133 MB at `bge-small-en-v1.5`'s size — into a new snapshot. The old snapshot is reported with its path and size and left alone; delete it by hand if you want the space.
+
+Each download also records the resolved commit in `codamigo-pin.json` in the model directory, which is what lets later loads run offline, and prints the model's real `embedding_dimensions` for you to paste into the config.
 
 ---
 
@@ -295,7 +299,9 @@ codamigo reset && codamigo index  # the store records its vector width, so switc
 
 Both are pinned to a fixed revision with per-file checksums, which is what makes `download-model` reproducible rather than just a corruption check.
 
-Any HuggingFace sentence-transformers repository id also works (`embedding_model: some-org/some-model`), but it is **not** checksum-verified, tracks `main`, and requires you to set `embedding_dimensions` yourself. Not every architecture loads: `nomic-ai/nomic-embed-text-v1.5`, for instance, is rejected by the current go-huggingface loader.
+Any HuggingFace sentence-transformers repository id also works (`embedding_model: some-org/some-model`), but it is **not** checksum-verified and requires you to set `embedding_dimensions` yourself — the value `download-model` prints. It resolves `main` at download time and is then pinned to that exact commit, so it never re-downloads on its own; only another `download-model` moves it. Not every architecture loads: `nomic-ai/nomic-embed-text-v1.5`, for instance, is rejected by the current go-huggingface loader.
+
+Loading a model never touches the network: the revision it would otherwise have to look up comes from `codamigo-pin.json` instead. Model directories that predate that file still load offline, deriving the revision from go-huggingface's own cached repository info with no re-download. `codamigo doctor` reports which of the two a model is using.
 
 ### Compute backends and speed
 
diff --git a/cmd/codamigo/doctor_cmd.go b/cmd/codamigo/doctor_cmd.go
index c893917..f3892d4 100644
--- a/cmd/codamigo/doctor_cmd.go
+++ b/cmd/codamigo/doctor_cmd.go
@@ -230,18 +230,31 @@ func reportProvider(cfg *config.Config, emb embedder.Embedder) {
 		fmt.Printf("[FAIL] Model: %v\n", err)
 		return
 	}
-	fmt.Printf("       Model: %s (%s)\n", model.DisplayName(), model.RepoID)
-	if !model.Pinned() {
-		fmt.Printf("[WARN] %s is not a built-in model, so its files are not checksum-verified\n", model.DisplayName())
-	}
-
 	root, err := localModelsRoot(cfg)
 	if err != nil {
 		fmt.Printf("[FAIL] Models directory: %v\n", err)
 		return
 	}
+	fmt.Printf("       Model: %s (%s)\n", model.DisplayName(), model.RepoID)
+	if !model.Pinned() {
+		fmt.Printf("[WARN] %s is not a built-in model, so its files are not checksum-verified\n", model.DisplayName())
+	}
+
 	if dir, err := localembed.ModelDir(root, model); err == nil {
-		if missing, err := localembed.MissingFiles(dir, model); err == nil && len(missing) == 0 {
+		switch pin, err := localembed.ReadPin(dir); {
+		case err == nil:
+			fmt.Printf("       Revision: %s (pinned %s)\n", pin.CommitHash, pin.ResolvedFrom)
+		case errors.Is(err, localembed.ErrNoPin):
+			fmt.Printf("       Revision: no pin file; derived from the cached repository info\n")
+			fmt.Printf("       Run 'codamigo download-model' to record one.\n")
+		default:
+			fmt.Printf("[WARN] Revision: %v\n", err)
+		}
+
+		resolved, _, err := localembed.ResolvePin(dir, model)
+		if err != nil {
+			warnIfModelMissing(root, model)
+		} else if missing, err := localembed.MissingFiles(dir, resolved); err == nil && len(missing) == 0 {
 			fmt.Printf("[OK]  Model files present: %s\n", dir)
 		} else {
 			warnIfModelMissing(root, model)
diff --git a/cmd/codamigo/download_cmd.go b/cmd/codamigo/download_cmd.go
index 1669138..7bf310a 100644
--- a/cmd/codamigo/download_cmd.go
+++ b/cmd/codamigo/download_cmd.go
@@ -105,6 +105,14 @@ func downloadModelCmd() *cli.Command {
 			}
 			fmt.Printf("      Model directory: %s\n", res.ModelDir)
 
+			if stale, err := localembed.SupersededSnapshots(modelDir, model, res.CommitHash); err == nil && len(stale) > 0 {
+				fmt.Printf("\n[WARN] %d superseded snapshot(s) remain in this model directory.\n", len(stale))
+				fmt.Print("       They are no longer used. Remove them by hand if you want the space:\n")
+				for _, s := range stale {
+					fmt.Printf("         %s (%s)\n", s.Path, humanBytes(s.Bytes))
+				}
+			}
+
 			if cmd.Bool("xla") || cmd.String("cuda") != "" {
 				if err := installPlugins(cmd); err != nil {
 					// Not fatal: the pure-Go backend still works, just slowly.
@@ -114,7 +122,7 @@ func downloadModelCmd() *cli.Command {
 				}
 			}
 
-			printLocalConfigSnippet(model)
+			printLocalConfigSnippet(model, res.Dimensions)
 			return nil
 		},
 	}
@@ -149,15 +157,19 @@ func installPlugins(cmd *cli.Command) error {
 
 // printLocalConfigSnippet tells the user exactly what to add to switch over,
 // including embedding_dimensions, which must match the model or the store will
-// refuse to open.
-func printLocalConfigSnippet(model localembed.Model) {
+// refuse to open. dimensions comes from the model's own config.json, so the
+// unpinned case no longer leaves the user to work it out.
+func printLocalConfigSnippet(model localembed.Model, dimensions int) {
 	name := model.DisplayName()
 	fmt.Printf("\nTo use it, add this to ~/.codamigo/global_settings.yml:\n\n")
 	fmt.Printf("  embedding_provider: local\n")
 	fmt.Printf("  embedding_model: %s\n", name)
-	if model.Dimensions > 0 {
+	switch {
+	case model.Dimensions > 0:
 		fmt.Printf("  embedding_dimensions: %d\n", model.Dimensions)
-	} else {
+	case dimensions > 0:
+		fmt.Printf("  embedding_dimensions: %d\n", dimensions)
+	default:
 		fmt.Printf("  embedding_dimensions: <the model's hidden size — codamigo will tell you>\n")
 	}
 	fmt.Printf("\nThe index stores its vector width, so switch providers with:\n")
@@ -188,7 +200,12 @@ func isModelDownloaded(root string, model localembed.Model) (bool, error) {
 	if err != nil {
 		return false, err
 	}
-	return localembed.IsDownloaded(dir, model)
+	resolved, _, err := localembed.ResolvePin(dir, model)
+	if err != nil {
+		// No resolvable revision means nothing usable is on disk.
+		return false, nil
+	}
+	return localembed.IsDownloaded(dir, resolved)
 }
 
 // warnIfModelMissing prints an actionable hint when the local provider is
@@ -198,7 +215,13 @@ func warnIfModelMissing(root string, model localembed.Model) {
 	if err != nil {
 		return
 	}
-	missing, err := localembed.MissingFiles(dir, model)
+	resolved, _, err := localembed.ResolvePin(dir, model)
+	if err != nil {
+		fmt.Printf("[FAIL] Model %s is not downloaded (%v)\n", model.DisplayName(), err)
+		fmt.Printf("       Run: codamigo download-model --model %s\n", model.DisplayName())
+		return
+	}
+	missing, err := localembed.MissingFiles(dir, resolved)
 	if err != nil {
 		if !errors.Is(err, os.ErrNotExist) {
 			fmt.Printf("[WARN] Could not inspect %s: %v\n", dir, err)
diff --git a/localembed/cache.go b/localembed/cache.go
index 22c1231..847527b 100644
--- a/localembed/cache.go
+++ b/localembed/cache.go
@@ -71,41 +71,17 @@ func flatRepoDir(repoID string) string {
 	return "models--" + strings.ReplaceAll(repoID, "/", "--")
 }
 
-// SnapshotDir returns the directory holding m's actual files inside modelDir.
+// SnapshotDir returns the directory holding m's files inside modelDir.
 //
-// A pinned model names its revision, so the path is exact. An unpinned model
-// tracks "main", whose commit hash is only known after the download, so the
-// single directory under snapshots/ is used instead. Returns
-// [ErrModelNotDownloaded] when there is nothing there yet.
+// m.Revision must already be a concrete commit hash — [ResolvePin] is what
+// guarantees that. Naming the path needs no filesystem access; whether the
+// files are actually present is [MissingFiles]' question.
 func SnapshotDir(modelDir string, m Model) (string, error) {
-	snapshots := filepath.Join(modelDir, flatRepoDir(m.RepoID), "snapshots")
-	if m.Revision != "" && m.Revision != "main" {
-		return filepath.Join(snapshots, m.Revision), nil
-	}
-	entries, err := os.ReadDir(snapshots)
-	if errors.Is(err, fs.ErrNotExist) {
-		return "", fmt.Errorf("%w: %s has no snapshot under %s", ErrModelNotDownloaded, m.DisplayName(), snapshots)
-	}
-	if err != nil {
-		return "", fmt.Errorf("reading %s: %w", snapshots, err)
-	}
-	var dirs []string
-	for _, e := range entries {
-		if e.IsDir() {
-			dirs = append(dirs, e.Name())
-		}
-	}
-	switch len(dirs) {
-	case 0:
-		return "", fmt.Errorf("%w: %s has no snapshot under %s", ErrModelNotDownloaded, m.DisplayName(), snapshots)
-	case 1:
-		return filepath.Join(snapshots, dirs[0]), nil
-	default:
-		// Several revisions of an unpinned model. Refuse rather than pick, since
-		// silently loading the wrong weights is worse than an actionable error.
-		return "", fmt.Errorf("%s has %d revisions under %s; pin embedding_model to a registry model "+
-			"or remove the directory and re-download", m.DisplayName(), len(dirs), snapshots)
+	if !isCommitHash(m.Revision) {
+		return "", fmt.Errorf("%s has unresolved revision %q; call ResolvePin first",
+			m.DisplayName(), m.Revision)
 	}
+	return filepath.Join(modelDir, flatRepoDir(m.RepoID), "snapshots", m.Revision), nil
 }
 
 // MissingFiles returns the manifest paths that are absent from modelDir or that
@@ -116,13 +92,6 @@ func SnapshotDir(modelDir string, m Model) (string, error) {
 // used rather than os.Lstat: a dangling link must count as missing.
 func MissingFiles(modelDir string, m Model) ([]string, error) {
 	snapshot, err := SnapshotDir(modelDir, m)
-	if errors.Is(err, ErrModelNotDownloaded) {
-		paths := make([]string, len(m.Files))
-		for i, f := range m.Files {
-			paths[i] = f.Path
-		}
-		return paths, nil
-	}
 	if err != nil {
 		return nil, err
 	}
@@ -151,3 +120,111 @@ func IsDownloaded(modelDir string, m Model) (bool, error) {
 	}
 	return len(missing) == 0, nil
 }
+
+// SnapshotInfo describes one snapshot directory on disk.
+type SnapshotInfo struct {
+	Path  string
+	Bytes int64
+}
+
+// SupersededSnapshots returns the snapshot directories under modelDir other
+// than keep, with their sizes.
+//
+// Moving an unpinned model to a newer upstream revision leaves the previous
+// snapshot behind — often gigabytes of it. Reporting them is deliberate:
+// deleting a working set of weights on the user's behalf is not this package's
+// decision. A missing snapshots directory is not an error, just an empty
+// result.
+func SupersededSnapshots(modelDir string, m Model, keep string) ([]SnapshotInfo, error) {
+	snapshots := filepath.Join(modelDir, flatRepoDir(m.RepoID), "snapshots")
+	entries, err := os.ReadDir(snapshots)
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("reading %s: %w", snapshots, err)
+	}
+	// Resolved once: every blob the kept snapshot still references. Any
+	// superseded snapshot entry pointing at one of these frees nothing when
+	// deleted, since removing a snapshot only removes its symlinks.
+	keepBlobs := blobTargets(filepath.Join(snapshots, keep))
+	var out []SnapshotInfo
+	for _, e := range entries {
+		if !e.IsDir() || e.Name() == keep {
+			continue
+		}
+		path := filepath.Join(snapshots, e.Name())
+		out = append(out, SnapshotInfo{Path: path, Bytes: dirSize(path, keepBlobs)})
+	}
+	return out, nil
+}
+
+// blobTargets resolves every symlink under snapshotDir to its target's
+// absolute, cleaned path. go-huggingface deduplicates identical file content
+// by etag: every entry in a snapshot directory is normally a symlink into a
+// shared blobs/ directory, so this is how [dirSize] tells which blobs the kept
+// snapshot still needs. snapshotDir need not exist (e.g. an already-deleted
+// keep); errors are swallowed and simply yield an empty set, since this is
+// only ever used to decide what a human-facing size figure should say.
+func blobTargets(snapshotDir string) map[string]struct{} {
+	targets := make(map[string]struct{})
+	_ = filepath.WalkDir(snapshotDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil //nolint:nilerr // an unreadable entry just contributes nothing
+		}
+		if resolved, ok := resolveSymlink(path); ok {
+			targets[resolved] = struct{}{}
+		}
+		return nil
+	})
+	return targets
+}
+
+// resolveSymlink reports the absolute, cleaned target of path if path is a
+// symlink, resolving a relative target against path's own directory the way
+// go-huggingface's snapshot entries do. ok is false for anything else,
+// including a plain file or any read error, so callers can just skip it.
+func resolveSymlink(path string) (string, bool) {
+	info, err := os.Lstat(path)
+	if err != nil || info.Mode()&os.ModeSymlink == 0 {
+		return "", false
+	}
+	target, err := os.Readlink(path)
+	if err != nil {
+		return "", false
+	}
+	if !filepath.IsAbs(target) {
+		target = filepath.Join(filepath.Dir(path), target)
+	}
+	return filepath.Clean(target), true
+}
+
+// dirSize reports the bytes actually reclaimable if the superseded snapshot
+// directory root were deleted.
+//
+// Snapshot entries are normally symlinks into a shared blobs/ directory,
+// deduplicated by etag: two snapshots of the same model share a blob for
+// every file whose content did not change between revisions. Deleting a
+// snapshot directory only removes its symlinks, never the blobs — so an entry
+// whose target is also referenced by the kept snapshot (keepBlobs) frees
+// nothing and must not be counted. A plain (non-symlinked) file is always
+// counted, since there is nothing else referencing it. Errors are swallowed:
+// this figure is reported to a human, never acted on.
+func dirSize(root string, keepBlobs map[string]struct{}) int64 {
+	var total int64
+	_ = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil //nolint:nilerr // an unreadable entry just does not count
+		}
+		if resolved, ok := resolveSymlink(path); ok {
+			if _, shared := keepBlobs[resolved]; shared {
+				return nil
+			}
+		}
+		if info, err := os.Stat(path); err == nil {
+			total += info.Size()
+		}
+		return nil
+	})
+	return total
+}
diff --git a/localembed/cache_test.go b/localembed/cache_test.go
index bb721ca..fd18935 100644
--- a/localembed/cache_test.go
+++ b/localembed/cache_test.go
@@ -1,7 +1,6 @@
 package localembed_test
 
 import (
-	"errors"
 	"os"
 	"path/filepath"
 	"slices"
@@ -96,52 +95,37 @@ func TestSnapshotDir_PinnedRevision(t *testing.T) {
 	}
 }
 
-func TestSnapshotDir_UnpinnedDiscoversRevision(t *testing.T) {
-	m, err := localembed.Lookup("org/model")
-	if err != nil {
-		t.Fatalf("Lookup: %v", err)
-	}
+func TestSnapshotDir_UsesRevisionDirectly(t *testing.T) {
 	root := t.TempDir()
-	snapshots := filepath.Join(root, "models--org--model", "snapshots", "abc123")
-	if err := os.MkdirAll(snapshots, 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	dir, err := localembed.SnapshotDir(root, m)
-	if err != nil {
-		t.Fatalf("SnapshotDir: %v", err)
-	}
-	if dir != snapshots {
-		t.Errorf("SnapshotDir = %q, want %q", dir, snapshots)
-	}
-}
+	m := localembed.Model{RepoID: "org/model", Revision: testHash}
+	want := filepath.Join(root, "models--org--model", "snapshots", testHash)
 
-func TestSnapshotDir_UnpinnedMissing(t *testing.T) {
-	m, err := localembed.Lookup("org/model")
+	got, err := localembed.SnapshotDir(root, m)
 	if err != nil {
-		t.Fatalf("Lookup: %v", err)
+		t.Fatalf("SnapshotDir: %v", err)
 	}
-	_, err = localembed.SnapshotDir(t.TempDir(), m)
-	if !errors.Is(err, localembed.ErrModelNotDownloaded) {
-		t.Errorf("SnapshotDir on an empty root = %v, want ErrModelNotDownloaded", err)
+	if got != want {
+		t.Errorf("SnapshotDir = %q, want %q", got, want)
 	}
 }
 
-// TestSnapshotDir_UnpinnedAmbiguous asserts we refuse rather than guess:
-// silently loading the wrong revision's weights would produce vectors that are
-// incompatible with the index without any error.
-func TestSnapshotDir_UnpinnedAmbiguous(t *testing.T) {
-	m, err := localembed.Lookup("org/model")
-	if err != nil {
-		t.Fatalf("Lookup: %v", err)
-	}
+func TestSnapshotDir_DoesNotRequireTheDirectoryToExist(t *testing.T) {
+	// SnapshotDir names a path; MissingFiles is what decides whether the files
+	// are there. Several revisions side by side is no longer ambiguous, because
+	// the pin says which one to use.
 	root := t.TempDir()
-	for _, rev := range []string{"abc", "def"} {
-		if err := os.MkdirAll(filepath.Join(root, "models--org--model", "snapshots", rev), 0o755); err != nil {
+	repoDir := filepath.Join(root, "models--org--model", "snapshots")
+	for _, rev := range []string{testHash, "89abcdef0123456789abcdef0123456789abcdef"} {
+		if err := os.MkdirAll(filepath.Join(repoDir, rev), 0o750); err != nil {
 			t.Fatalf("MkdirAll: %v", err)
 		}
 	}
-	if _, err := localembed.SnapshotDir(root, m); err == nil {
-		t.Error("SnapshotDir with two revisions = nil error, want refusal")
+	got, err := localembed.SnapshotDir(root, localembed.Model{RepoID: "org/model", Revision: testHash})
+	if err != nil {
+		t.Fatalf("SnapshotDir with two revisions present: %v", err)
+	}
+	if got != filepath.Join(repoDir, testHash) {
+		t.Errorf("SnapshotDir = %q, want the pinned revision %q", got, filepath.Join(repoDir, testHash))
 	}
 }
 
@@ -262,6 +246,132 @@ func TestMissingFiles_DanglingSymlink(t *testing.T) {
 	}
 }
 
+func TestSupersededSnapshots(t *testing.T) {
+	const stale = "89abcdef0123456789abcdef0123456789abcdef"
+	root := t.TempDir()
+	snapshots := filepath.Join(root, "models--org--model", "snapshots")
+	for _, rev := range []string{testHash, stale} {
+		if err := os.MkdirAll(filepath.Join(snapshots, rev), 0o750); err != nil {
+			t.Fatalf("MkdirAll: %v", err)
+		}
+		if err := os.WriteFile(filepath.Join(snapshots, rev, "w.bin"), []byte("12345"), 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+	}
+	got, err := localembed.SupersededSnapshots(root, localembed.Model{RepoID: "org/model"}, testHash)
+	if err != nil {
+		t.Fatalf("SupersededSnapshots: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("got %d superseded snapshots, want 1: %+v", len(got), got)
+	}
+	if got[0].Path != filepath.Join(snapshots, stale) {
+		t.Errorf("Path = %q, want %q", got[0].Path, filepath.Join(snapshots, stale))
+	}
+	if got[0].Bytes != 5 {
+		t.Errorf("Bytes = %d, want 5", got[0].Bytes)
+	}
+}
+
+func TestSupersededSnapshots_NoneWhenOnlyKeepExists(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "models--org--model", "snapshots", testHash), 0o750); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	got, err := localembed.SupersededSnapshots(root, localembed.Model{RepoID: "org/model"}, testHash)
+	if err != nil {
+		t.Fatalf("SupersededSnapshots: %v", err)
+	}
+	if len(got) != 0 {
+		t.Errorf("got %+v, want none", got)
+	}
+}
+
+func TestSupersededSnapshots_MissingDirIsNotAnError(t *testing.T) {
+	got, err := localembed.SupersededSnapshots(t.TempDir(), localembed.Model{RepoID: "org/model"}, testHash)
+	if err != nil {
+		t.Fatalf("SupersededSnapshots on empty root: %v", err)
+	}
+	if len(got) != 0 {
+		t.Errorf("got %+v, want none", got)
+	}
+}
+
+// TestSupersededSnapshots_SharedBlobsNotCounted covers go-huggingface's real
+// layout: snapshot entries are symlinks into a shared blobs/ directory,
+// deduplicated by etag. Deleting a superseded snapshot only removes its
+// symlinks, not blobs still referenced by the kept snapshot, so those bytes
+// are not actually reclaimable and must not be counted. Without the fix this
+// reports the sum of both blobs (shared + unique) instead of only the unique
+// one.
+func TestSupersededSnapshots_SharedBlobsNotCounted(t *testing.T) {
+	const stale = "89abcdef0123456789abcdef0123456789abcdef"
+	root := t.TempDir()
+	repoDir := filepath.Join(root, "models--org--model")
+	blobs := filepath.Join(repoDir, "blobs")
+	if err := os.MkdirAll(blobs, 0o750); err != nil {
+		t.Fatalf("MkdirAll blobs: %v", err)
+	}
+	sharedBlob := filepath.Join(blobs, "shared")
+	keepOnlyBlob := filepath.Join(blobs, "keep-only")
+	staleOnlyBlob := filepath.Join(blobs, "stale-only")
+	for path, content := range map[string]string{
+		sharedBlob:    "shared-weights-unchanged",
+		keepOnlyBlob:  "new-config",
+		staleOnlyBlob: "only-in-stale",
+	} {
+		if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+			t.Fatalf("WriteFile %s: %v", path, err)
+		}
+	}
+
+	snapshots := filepath.Join(repoDir, "snapshots")
+	keepDir := filepath.Join(snapshots, testHash)
+	staleDir := filepath.Join(snapshots, stale)
+	if err := os.MkdirAll(keepDir, 0o750); err != nil {
+		t.Fatalf("MkdirAll keep: %v", err)
+	}
+	if err := os.MkdirAll(staleDir, 0o750); err != nil {
+		t.Fatalf("MkdirAll stale: %v", err)
+	}
+
+	// The kept snapshot's weights did not change (still points at the shared
+	// blob) but its config did (points at a blob the stale snapshot never
+	// referenced). This link uses a relative target, matching what
+	// go-huggingface actually writes (e.g. "../../blobs/<etag>"), so
+	// resolveSymlink's relative-path branch is exercised too, not just the
+	// absolute-path one the other three links below use.
+	sharedBlobRel, err := filepath.Rel(keepDir, sharedBlob)
+	if err != nil {
+		t.Fatalf("Rel: %v", err)
+	}
+	if err := os.Symlink(sharedBlobRel, filepath.Join(keepDir, "model.bin")); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	if err := os.Symlink(keepOnlyBlob, filepath.Join(keepDir, "config.json")); err != nil {
+		t.Fatalf("Symlink: %v", err)
+	}
+	// The stale snapshot shares the weights blob but has its own extra file.
+	if err := os.Symlink(sharedBlob, filepath.Join(staleDir, "model.bin")); err != nil {
+		t.Fatalf("Symlink: %v", err)
+	}
+	if err := os.Symlink(staleOnlyBlob, filepath.Join(staleDir, "extra.bin")); err != nil {
+		t.Fatalf("Symlink: %v", err)
+	}
+
+	got, err := localembed.SupersededSnapshots(root, localembed.Model{RepoID: "org/model"}, testHash)
+	if err != nil {
+		t.Fatalf("SupersededSnapshots: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("got %d superseded snapshots, want 1: %+v", len(got), got)
+	}
+	want := int64(len("only-in-stale"))
+	if got[0].Bytes != want {
+		t.Errorf("Bytes = %d, want %d (only the blob not shared with the kept snapshot)", got[0].Bytes, want)
+	}
+}
+
 // writeSized creates a file of exactly size bytes, so size checks can be
 // exercised without materializing real weights.
 func writeSized(t *testing.T, path string, size int64) {
diff --git a/localembed/download.go b/localembed/download.go
index ff6fcf4..bb857aa 100644
--- a/localembed/download.go
+++ b/localembed/download.go
@@ -4,12 +4,14 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
 	"strings"
+	"time"
 
 	"github.com/gomlx/go-huggingface/hub"
 )
@@ -44,6 +46,14 @@ type DownloadResult struct {
 	// Verified reports whether checksums were compared. False for an unpinned
 	// repository id, where there is nothing to compare against.
 	Verified bool
+	// CommitHash is the upstream revision the files came from, resolved from
+	// the repository info. Recorded in the pin file so later loads need no
+	// network round trip to rediscover it.
+	CommitHash string
+	// Dimensions is the model's hidden size, read from the downloaded
+	// config.json. Zero when it could not be read. Reported so the caller can
+	// print a real embedding_dimensions value instead of a placeholder.
+	Dimensions int
 }
 
 // Download fetches every manifest file for opts.Model into opts.ModelDir and,
@@ -95,10 +105,43 @@ func Download(ctx context.Context, opts DownloadOptions) (*DownloadResult, error
 	// DownloadInfo resolves the revision and the file list. It does not take a
 	// context upstream, so Ctrl-C during this step is only noticed at the next
 	// ctx check below.
-	if err := repo.DownloadInfo(opts.Force); err != nil {
+	//
+	// Forced unconditionally: download-model is the one command that is meant to
+	// consult upstream, and DownloadInfo otherwise reuses a cached info file and
+	// would never observe that the tracked branch had moved. Loads never reach
+	// this code — they answer the same query from the pin file instead.
+	if err := repo.DownloadInfo(true); err != nil {
 		return nil, downloadError(err, m, opts.Token)
 	}
 
+	// Resolve the concrete commit hash once, right after DownloadInfo wrote the
+	// info file, and before the per-file loop. SnapshotDir now requires a
+	// concrete hash — existingFile (via fetchFile) would otherwise be handed
+	// m's unresolved "main" for an unpinned model and silently treat every file
+	// as absent, turning an idempotent second run into a full re-download.
+	rev := m.Revision
+	if rev == "" {
+		rev = "main"
+	}
+	hash, infoBody, err := readDownloadInfo(opts.ModelDir, m, rev)
+	if err != nil {
+		return nil, err
+	}
+	opts.Model.Revision = hash
+
+	// An unpinned repository id's manifest may still be missing files that
+	// only modules.json itself reveals (a Dense projection, a Normalize
+	// step) — discover them now, before the loop below decides the download
+	// is complete. Registry models keep their hand-verified manifest as is.
+	if !m.Registered {
+		expanded, err := expandUnpinnedManifest(ctx, repo, opts, m, infoBody)
+		if err != nil {
+			return nil, err
+		}
+		m.Files = expanded
+		opts.Model.Files = expanded
+	}
+
 	result := &DownloadResult{ModelDir: opts.ModelDir, Verified: m.Pinned()}
 	for _, f := range m.Files {
 		if err := ctx.Err(); err != nil {
@@ -118,9 +161,121 @@ func Download(ctx context.Context, opts DownloadOptions) (*DownloadResult, error
 		}
 	}
 
+	pin, err := writeDownloadPin(opts, rev, hash, infoBody)
+	if err != nil {
+		return nil, err
+	}
+	result.CommitHash = pin.CommitHash
+	result.Dimensions = pin.Dimensions
+
 	return result, nil
 }
 
+// readDownloadInfo reads and parses the repository info file go-huggingface
+// just wrote for rev, returning the resolved commit hash and the raw body as
+// read from disk. Reading the file directly rather than calling repo.Info()
+// avoids a nil dereference nilaway would reject. The body is what becomes the
+// pin's RepoInfo; note that WritePin's json.Marshal compacts and HTML-escapes
+// it, so what the shim later replays is semantically equivalent, not
+// byte-identical, to what is read here.
+func readDownloadInfo(modelDir string, m Model, rev string) (hash string, body []byte, err error) {
+	repoDir := filepath.Join(modelDir, flatRepoDir(m.RepoID))
+	infoPath := filepath.Join(repoDir, "info", rev)
+	// #nosec G304 -- infoPath is inside the model directory this call just populated
+	body, err = os.ReadFile(infoPath)
+	if err != nil {
+		return "", nil, fmt.Errorf("reading repository info for %s at %s: %w", m.DisplayName(), infoPath, err)
+	}
+	var meta struct {
+		SHA string `json:"sha"`
+	}
+	if err := json.Unmarshal(body, &meta); err != nil {
+		return "", nil, fmt.Errorf("parsing repository info for %s at %s: %w", m.DisplayName(), infoPath, err)
+	}
+	if !isCommitHash(meta.SHA) {
+		return "", nil, fmt.Errorf("repository info for %s at %s has no valid sha", m.DisplayName(), infoPath)
+	}
+	return meta.SHA, body, nil
+}
+
+// writeDownloadPin records the revision this download resolved to, so loading
+// the model later needs no network access. hash and body are the values
+// [readDownloadInfo] already parsed from the info file before the per-file
+// loop, reused here rather than read a second time.
+func writeDownloadPin(opts DownloadOptions, rev, hash string, body []byte) (Pin, error) {
+	m := opts.Model
+	repoDir := filepath.Join(opts.ModelDir, flatRepoDir(m.RepoID))
+	pin := Pin{
+		RepoID:       m.RepoID,
+		CommitHash:   hash,
+		ResolvedFrom: rev,
+		ResolvedAt:   time.Now().UTC(),
+		Dimensions:   snapshotHiddenSize(repoDir, hash),
+		RepoInfo:     body,
+	}
+	if err := WritePin(opts.ModelDir, pin); err != nil {
+		return Pin{}, err
+	}
+	return pin, nil
+}
+
+// snapshotHiddenSize reads hidden_size from the downloaded config.json.
+//
+// This is the same quantity New cross-checks against embedding_dimensions via
+// the loaded model's Config.HiddenSize, so recording it introduces no second
+// notion of width. Failure returns 0: the value is only used to print a helpful
+// default, and a download must not fail because of it.
+func snapshotHiddenSize(repoDir, commitHash string) int {
+	// #nosec G304 -- path is inside the model directory this call just populated
+	body, err := os.ReadFile(filepath.Join(repoDir, "snapshots", commitHash, "config.json"))
+	if err != nil {
+		return 0
+	}
+	var cfg struct {
+		HiddenSize int `json:"hidden_size"`
+	}
+	if err := json.Unmarshal(body, &cfg); err != nil {
+		return 0
+	}
+	return cfg.HiddenSize
+}
+
+// expandUnpinnedManifest fetches modules.json ahead of the main download loop
+// below and folds in whatever extra module files it declares, via
+// [expandManifest]. Fetching it early — rather than waiting for the main loop
+// to reach it in manifest order — is what lets the loop's single pass over
+// m.Files download everything a Dense projection or Normalize module needs,
+// instead of only ever knowing about the plain Transformer+Pooling pair.
+//
+// The fetch here is not wasted work: fetchFile is idempotent, so the main loop
+// downloading modules.json again a moment later just finds it already present.
+func expandUnpinnedManifest(ctx context.Context, repo *hub.Repo, opts DownloadOptions, m Model, infoBody []byte) ([]ManifestFile, error) {
+	modulesFile, ok := findManifestFile(m.Files, "modules.json")
+	if !ok {
+		return m.Files, nil
+	}
+	path, _, err := fetchFile(ctx, repo, opts, modulesFile)
+	if err != nil {
+		return nil, err
+	}
+	// #nosec G304 -- path is inside the model directory this call just populated
+	modulesJSON, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("reading modules.json to discover extra model files: %w", err)
+	}
+	return expandManifest(modulesJSON, infoBody, m.Files)
+}
+
+// findManifestFile looks up one manifest entry by path.
+func findManifestFile(files []ManifestFile, path string) (ManifestFile, bool) {
+	for _, f := range files {
+		if f.Path == path {
+			return f, true
+		}
+	}
+	return ManifestFile{}, false
+}
+
 // fetchFile downloads one manifest file unless an acceptable copy is already
 // present, and verifies it before returning. It reports whether a download
 // actually happened so the caller can distinguish a no-op run.
diff --git a/localembed/download_test.go b/localembed/download_test.go
index 17cd228..e7ce77a 100644
--- a/localembed/download_test.go
+++ b/localembed/download_test.go
@@ -11,6 +11,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"testing"
 
@@ -30,6 +31,9 @@ type fakeHub struct {
 	// requests counts GETs of file content, so an idempotent second run can be
 	// distinguished from a re-download.
 	requests map[string]int
+	// lfsSHA256, keyed by rfilename, is reported as that sibling's lfs.sha256
+	// in the repository info, the way HuggingFace does for large files.
+	lfsSHA256 map[string]string
 }
 
 const fakeRevision = "0123456789abcdef0123456789abcdef01234567"
@@ -46,7 +50,11 @@ func newFakeHub(t *testing.T, repoID string, files map[string]string) *fakeHub {
 		}
 		siblings := make([]map[string]any, 0, len(files))
 		for name, content := range files {
-			siblings = append(siblings, map[string]any{"rfilename": name, "size": len(content)})
+			sib := map[string]any{"rfilename": name, "size": len(content)}
+			if sum, ok := hub.lfsSHA256[name]; ok {
+				sib["lfs"] = map[string]any{"sha256": sum, "size": len(content)}
+			}
+			siblings = append(siblings, sib)
 		}
 		w.Header().Set("Content-Type", "application/json")
 		_ = json.NewEncoder(w).Encode(map[string]any{
@@ -204,6 +212,49 @@ func TestDownload_IdempotentSkip(t *testing.T) {
 	}
 }
 
+// TestDownload_IdempotentSkipUnpinned is the unpinned twin of
+// TestDownload_IdempotentSkip: a repository id tracking "main" has
+// Model.Revision == "main" going into Download, which SnapshotDir now rejects
+// outright. A second run must still resolve the concrete commit hash before
+// checking what is already on disk, or every file gets reported as
+// downloaded again instead of skipped.
+func TestDownload_IdempotentSkipUnpinned(t *testing.T) {
+	files, order := testFiles()
+	repoID := "test-org/unpinned-model"
+	hub := newFakeHub(t, repoID, files)
+	manifest := make([]localembed.ManifestFile, 0, len(order))
+	for _, name := range order {
+		manifest = append(manifest, localembed.ManifestFile{Path: name})
+	}
+	m := localembed.Model{RepoID: repoID, Revision: "main", Files: manifest}
+	dir := t.TempDir()
+	opts := localembed.DownloadOptions{Model: m, ModelDir: dir, Endpoint: hub.URL}
+
+	if _, err := localembed.Download(t.Context(), opts); err != nil {
+		t.Fatalf("first Download: %v", err)
+	}
+	firstCounts := map[string]int{}
+	for k, v := range hub.requests {
+		firstCounts[k] = v
+	}
+
+	res, err := localembed.Download(t.Context(), opts)
+	if err != nil {
+		t.Fatalf("second Download: %v", err)
+	}
+	if len(res.Skipped) != len(order) {
+		t.Errorf("Skipped = %v, want all %d files on a repeat run", res.Skipped, len(order))
+	}
+	if len(res.Downloaded) != 0 {
+		t.Errorf("Downloaded = %v, want none on a repeat run", res.Downloaded)
+	}
+	for name, count := range hub.requests {
+		if count != firstCounts[name] {
+			t.Errorf("%s was re-fetched (%d then %d requests)", name, firstCounts[name], count)
+		}
+	}
+}
+
 func TestDownload_ForceRefetches(t *testing.T) {
 	files, order := testFiles()
 	repoID := "test-org/test-model"
@@ -402,3 +453,168 @@ func TestDownload_UnpinnedIsNotVerified(t *testing.T) {
 		t.Error("Verified = true for an unpinned model")
 	}
 }
+
+func TestDownload_WritesPin(t *testing.T) {
+	files, order := testFiles()
+	repoID := "test-org/test-model"
+	hub := newFakeHub(t, repoID, files)
+	m := pinnedModel(repoID, files, order)
+	dir := t.TempDir()
+
+	res, err := localembed.Download(t.Context(), localembed.DownloadOptions{
+		Model: m, ModelDir: dir, Endpoint: hub.URL,
+	})
+	if err != nil {
+		t.Fatalf("Download: %v", err)
+	}
+	if res.CommitHash != fakeRevision {
+		t.Errorf("CommitHash = %q, want %q", res.CommitHash, fakeRevision)
+	}
+	// testFiles() serves config.json as {"hidden_size": 8}.
+	if res.Dimensions != 8 {
+		t.Errorf("Dimensions = %d, want 8", res.Dimensions)
+	}
+
+	pin, err := localembed.ReadPin(dir)
+	if err != nil {
+		t.Fatalf("ReadPin after Download: %v", err)
+	}
+	if pin.CommitHash != fakeRevision {
+		t.Errorf("pin.CommitHash = %q, want %q", pin.CommitHash, fakeRevision)
+	}
+	if pin.RepoID != repoID {
+		t.Errorf("pin.RepoID = %q, want %q", pin.RepoID, repoID)
+	}
+	if pin.Dimensions != 8 {
+		t.Errorf("pin.Dimensions = %d, want 8", pin.Dimensions)
+	}
+	if pin.ResolvedAt.IsZero() {
+		t.Error("pin.ResolvedAt is zero")
+	}
+	// The shim replays RepoInfo to go-huggingface, so it must be parseable as
+	// the repository info and carry the same sha.
+	var meta struct {
+		SHA string `json:"sha"`
+	}
+	if err := json.Unmarshal(pin.RepoInfo, &meta); err != nil {
+		t.Fatalf("pin.RepoInfo is not valid JSON: %v", err)
+	}
+	if meta.SHA != fakeRevision {
+		t.Errorf("pin.RepoInfo sha = %q, want %q", meta.SHA, fakeRevision)
+	}
+}
+
+// TestDownload_DiscoversExtraModuleFiles is the regression test for
+// google/embeddinggemma-300m: an unpinned repository id whose modules.json
+// declares a Dense projection module must have that module's files
+// downloaded too, not just the plain Transformer+Pooling pair standardManifest
+// assumes.
+func TestDownload_DiscoversExtraModuleFiles(t *testing.T) {
+	files := map[string]string{
+		"config.json":                       `{"hidden_size": 8}`,
+		"config_sentence_transformers.json": `{}`,
+		"modules.json": `[
+			{"idx": 0, "name": "0", "path": "", "type": "sentence_transformers.models.Transformer"},
+			{"idx": 1, "name": "1", "path": "1_Pooling", "type": "sentence_transformers.models.Pooling"},
+			{"idx": 2, "name": "2", "path": "2_Dense", "type": "sentence_transformers.models.Dense"}
+		]`,
+		"tokenizer.json":            `{}`,
+		"tokenizer_config.json":     `{}`,
+		"1_Pooling/config.json":     `{"pooling_mode_cls_token": true}`,
+		"model.safetensors":         strings.Repeat("w", 512),
+		"2_Dense/config.json":       `{"in_features": 8, "out_features": 8}`,
+		"2_Dense/model.safetensors": strings.Repeat("d", 64),
+	}
+	repoID := "test-org/dense-model"
+	hub := newFakeHub(t, repoID, files)
+	hub.lfsSHA256 = map[string]string{
+		"2_Dense/model.safetensors": func() string {
+			sum := sha256.Sum256([]byte(files["2_Dense/model.safetensors"]))
+			return hex.EncodeToString(sum[:])
+		}(),
+	}
+
+	base := make([]localembed.ManifestFile, 0)
+	for _, p := range []string{
+		"config.json", "config_sentence_transformers.json", "modules.json",
+		"tokenizer.json", "tokenizer_config.json", "1_Pooling/config.json", "model.safetensors",
+	} {
+		base = append(base, localembed.ManifestFile{Path: p})
+	}
+	m := localembed.Model{RepoID: repoID, Revision: "main", Files: base}
+	dir := t.TempDir()
+
+	res, err := localembed.Download(t.Context(), localembed.DownloadOptions{
+		Model: m, ModelDir: dir, Endpoint: hub.URL,
+	})
+	if err != nil {
+		t.Fatalf("Download: %v", err)
+	}
+	wantDownloaded := []string{"2_Dense/config.json", "2_Dense/model.safetensors"}
+	for _, want := range wantDownloaded {
+		if !slices.Contains(res.Downloaded, want) {
+			t.Errorf("Downloaded = %v, want it to include %q", res.Downloaded, want)
+		}
+	}
+
+	snapshot, err := localembed.SnapshotDir(dir, localembed.Model{RepoID: repoID, Revision: fakeRevision})
+	if err != nil {
+		t.Fatalf("SnapshotDir: %v", err)
+	}
+	for _, name := range []string{"2_Dense/config.json", "2_Dense/model.safetensors"} {
+		if _, err := os.Stat(filepath.Join(snapshot, filepath.FromSlash(name))); err != nil {
+			t.Errorf("%s not on disk after Download: %v", name, err)
+		}
+	}
+
+	// The model is now actually complete: MissingFiles on the same discovery
+	// must agree, which is what New relies on via ResolvePin at load time.
+	resolved, _, err := localembed.ResolvePin(dir, m)
+	if err != nil {
+		t.Fatalf("ResolvePin: %v", err)
+	}
+	missing, err := localembed.MissingFiles(dir, resolved)
+	if err != nil {
+		t.Fatalf("MissingFiles: %v", err)
+	}
+	if len(missing) != 0 {
+		t.Errorf("MissingFiles = %v, want none after Download discovered the Dense module", missing)
+	}
+}
+
+func TestDownload_WritesPinForUnpinnedRepo(t *testing.T) {
+	// The case that motivated all of this: a bare repository id tracking "main".
+	files, order := testFiles()
+	repoID := "test-org/test-model"
+	hub := newFakeHub(t, repoID, files)
+	manifest := make([]localembed.ManifestFile, 0, len(order))
+	for _, name := range order {
+		manifest = append(manifest, localembed.ManifestFile{Path: name})
+	}
+	m := localembed.Model{RepoID: repoID, Revision: "main", Files: manifest}
+	dir := t.TempDir()
+
+	if _, err := localembed.Download(t.Context(), localembed.DownloadOptions{
+		Model: m, ModelDir: dir, Endpoint: hub.URL,
+	}); err != nil {
+		t.Fatalf("Download: %v", err)
+	}
+	pin, err := localembed.ReadPin(dir)
+	if err != nil {
+		t.Fatalf("ReadPin: %v", err)
+	}
+	if pin.CommitHash != fakeRevision {
+		t.Errorf("pin.CommitHash = %q, want %q", pin.CommitHash, fakeRevision)
+	}
+	if pin.ResolvedFrom != "main" {
+		t.Errorf("pin.ResolvedFrom = %q, want \"main\"", pin.ResolvedFrom)
+	}
+	// And the resolved pin must now hand back a concrete revision.
+	resolved, _, err := localembed.ResolvePin(dir, m)
+	if err != nil {
+		t.Fatalf("ResolvePin: %v", err)
+	}
+	if resolved.Revision != fakeRevision {
+		t.Errorf("resolved Revision = %q, want %q", resolved.Revision, fakeRevision)
+	}
+}
diff --git a/localembed/embedder.go b/localembed/embedder.go
index 5c8e153..b938d03 100644
--- a/localembed/embedder.go
+++ b/localembed/embedder.go
@@ -167,6 +167,13 @@ func New(opts Options) (*Embedder, error) {
 	if err != nil {
 		return nil, err
 	}
+	// Resolve the revision before anything looks for files: the snapshot
+	// directory is named after the commit hash, so MissingFiles cannot find
+	// anything until the hash is known.
+	descriptor, pin, err := ResolvePin(modelDir, descriptor)
+	if err != nil {
+		return nil, err
+	}
 	missing, err := MissingFiles(modelDir, descriptor)
 	if err != nil {
 		return nil, err
@@ -177,19 +184,43 @@ func New(opts Options) (*Embedder, error) {
 			ErrModelNotDownloaded, descriptor.DisplayName(), len(missing), modelDir, missing[0], descriptor.DisplayName())
 	}
 
-	repo := hub.New(descriptor.RepoID).WithCacheDir(modelDir)
-	if descriptor.Revision != "" {
-		repo = repo.WithRevision(descriptor.Revision)
+	// go-huggingface re-resolves the revision over the network on every load and
+	// ignores its own on-disk cache, so point it at a local shim that answers
+	// from the pin instead. Every *hub.Repo access happens below, during
+	// loading, so the shim can be shut down as soon as New returns.
+	shim, err := startInfoShim(descriptor, pin)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = shim.Close() }()
+
+	// loadErr wraps a failure from any call below that can reach *hub.Repo. If
+	// the shim refused a request, that is almost always the real cause: a file
+	// outside standardManifest that the local snapshot never had. Naming it beats
+	// surfacing the underlying HTTP error, which just says the URL 404ed.
+	loadErr := func(err error, fallback string) error {
+		if missed := shim.missedPaths(); len(missed) > 0 {
+			return fmt.Errorf("%w: %s is not in the local snapshot for %s. "+
+				"Run: codamigo download-model --model %s",
+				ErrModelNotDownloaded, missed[0], descriptor.DisplayName(), descriptor.DisplayName())
+		}
+		return fmt.Errorf("%s: %w", fallback, err)
 	}
+
+	repo := hub.New(descriptor.RepoID).
+		WithCacheDir(modelDir).
+		WithRevision(descriptor.Revision).
+		WithEndpoint(shim.URL)
 	repo.Verbosity = 0
 	// The files are already local, but LoadModel needs the repo's file index.
 	if err := repo.DownloadInfo(false); err != nil {
-		return nil, fmt.Errorf("reading local model info for %s: %w", descriptor.DisplayName(), err)
+		return nil, fmt.Errorf("%w: reading local model info for %s: %v. Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, descriptor.DisplayName(), err, descriptor.DisplayName())
 	}
 
 	hfModel, err := transformer.LoadModel(repo)
 	if err != nil {
-		return nil, fmt.Errorf("loading %s: %w", descriptor.DisplayName(), err)
+		return nil, loadErr(err, fmt.Sprintf("loading %s", descriptor.DisplayName()))
 	}
 	dim := hfModel.Config.HiddenSize
 	if err := checkDimensions(descriptor, opts.Dimensions, dim); err != nil {
@@ -198,7 +229,7 @@ func New(opts Options) (*Embedder, error) {
 
 	tokenizer, err := hfModel.GetTokenizer()
 	if err != nil {
-		return nil, fmt.Errorf("loading tokenizer for %s: %w", descriptor.DisplayName(), err)
+		return nil, loadErr(err, fmt.Sprintf("loading tokenizer for %s", descriptor.DisplayName()))
 	}
 	padID, err := tokenizer.SpecialTokenID(api.TokPad)
 	if err != nil {
@@ -232,7 +263,7 @@ func New(opts Options) (*Embedder, error) {
 	}
 	if err := hfModel.LoadStore(backend, store); err != nil {
 		cleanup()
-		return nil, fmt.Errorf("loading weights for %s onto %s: %w", descriptor.DisplayName(), backendName, err)
+		return nil, loadErr(err, fmt.Sprintf("loading weights for %s onto %s", descriptor.DisplayName(), backendName))
 	}
 
 	// seqLen is derived inside the graph from the pad token rather than passed as
diff --git a/localembed/errors.go b/localembed/errors.go
index d4d1435..ef207c0 100644
--- a/localembed/errors.go
+++ b/localembed/errors.go
@@ -44,4 +44,9 @@ var (
 	// ErrUnknownModel reports that a model short name is not in the registry and
 	// is not a usable HuggingFace repository id.
 	ErrUnknownModel = errors.New("unknown model")
+
+	// ErrNoPin reports that a model directory has no usable pin file. It is an
+	// internal signal, not a user-facing failure: callers fall through to
+	// deriving the revision from go-huggingface's cached info file.
+	ErrNoPin = errors.New("no usable pin file")
 )
diff --git a/localembed/infoshim.go b/localembed/infoshim.go
new file mode 100644
index 0000000..2f9dcd7
--- /dev/null
+++ b/localembed/infoshim.go
@@ -0,0 +1,144 @@
+package localembed
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+)
+
+// infoShim answers the one HuggingFace API call go-huggingface insists on
+// making, from data already on this machine.
+//
+// go-huggingface has no offline mode. hub.Repo.readCommitHashForRevision
+// computes forceDownload from !revisionHashRefreshed, which is false on every
+// freshly constructed Repo, so DownloadInfo re-fetches the repository info over
+// the network and ignores the copy cached on disk. Its only product is the name
+// of the snapshot directory. There is no way to inject a transport — the
+// http.Client is built inline in the library's internal/downloader — so the
+// only public lever is WithEndpoint. Pointing it at this shim turns that
+// mandatory call into a loopback request that always succeeds and always
+// returns the pinned revision.
+//
+// The shim serves the pin's in-memory RepoInfo rather than reading a file per
+// request, because LockedDownload deletes its destination before fetching it:
+// the info file on disk is unlinked while this request is in flight.
+type infoShim struct {
+	URL string
+
+	srv      *http.Server
+	listener net.Listener
+	done     chan struct{}
+
+	mu     sync.Mutex
+	missed []string
+}
+
+// startInfoShim binds a loopback listener and starts serving. The caller must
+// Close it; it is only needed for the span of [New], since every *hub.Repo
+// access happens during loading.
+func startInfoShim(m Model, p Pin) (*infoShim, error) {
+	if err := validatePinRepoInfo(m, p); err != nil {
+		return nil, err
+	}
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return nil, fmt.Errorf("starting local model info server for %s: %w", m.DisplayName(), err)
+	}
+	s := &infoShim{
+		URL:      "http://" + listener.Addr().String(),
+		listener: listener,
+		done:     make(chan struct{}),
+	}
+	// The path go-huggingface builds is
+	// <endpoint>/api/models/<id>/revision/<rev>, optionally with ?blobs=true.
+	wantPath := "/api/models/" + m.RepoID + "/revision/" + p.CommitHash
+	// Copied, not aliased: json.RawMessage is a []byte, so []byte(p.RepoInfo)
+	// would share the caller's array and let a later write change what is
+	// served while a request is in flight.
+	body := append([]byte(nil), p.RepoInfo...)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != wantPath {
+			s.recordMiss(r.URL.Path)
+			// Naming the path makes the eventual load failure legible: it is
+			// almost always a manifest file that is not in the local snapshot.
+			http.Error(w, fmt.Sprintf("%s is not available from the local model cache", r.URL.Path),
+				http.StatusNotFound)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(body)
+	})
+
+	s.srv = &http.Server{
+		Handler: mux,
+		// gosec G112.
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+	go func() {
+		defer close(s.done)
+		// Discarded deliberately. The one failure worth reporting is a bind
+		// failure, and net.Listen above has already returned it; every other
+		// Serve error — including the expected ErrServerClosed from Close —
+		// surfaces as the load error the caller is about to report anyway.
+		_ = s.srv.Serve(listener)
+	}()
+	return s, nil
+}
+
+// validatePinRepoInfo confirms p.RepoInfo actually describes the commit p
+// claims, before anything downstream can act on it.
+//
+// ReadPin only validates that CommitHash looks like a commit hash — it never
+// inspects RepoInfo. Without this check, a pin with a valid hash but an
+// empty, unparseable, or mismatched RepoInfo would reach go-huggingface's
+// DownloadInfo, whose LockedDownload unlinks info/<hash> before finding out
+// the replacement is unusable: the model becomes unloadable offline until a
+// network re-download, destroying the exact file the offline path depends
+// on. Running this before startInfoShim's listener starts guarantees nothing
+// downstream gets the chance to unlink that file.
+func validatePinRepoInfo(m Model, p Pin) error {
+	if len(p.RepoInfo) == 0 {
+		return fmt.Errorf("%w: pin for %s has no repo_info. Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, m.DisplayName(), m.DisplayName())
+	}
+	var meta struct {
+		SHA string `json:"sha"`
+	}
+	if err := json.Unmarshal(p.RepoInfo, &meta); err != nil {
+		return fmt.Errorf("%w: pin for %s has unparseable repo_info: %v. Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, m.DisplayName(), err, m.DisplayName())
+	}
+	if meta.SHA != p.CommitHash {
+		return fmt.Errorf("%w: pin for %s names commit %s but repo_info sha is %s. Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, m.DisplayName(), p.CommitHash, meta.SHA, m.DisplayName())
+	}
+	return nil
+}
+
+func (s *infoShim) recordMiss(path string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.missed = append(s.missed, path)
+}
+
+// missedPaths returns the paths the shim refused, in request order. A non-empty
+// result means something asked for a file the local snapshot does not have.
+func (s *infoShim) missedPaths() []string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return append([]string(nil), s.missed...)
+}
+
+// Close stops the server and waits for its goroutine to finish. The returned
+// error is whatever closing the listener reported; http.Server.Close never
+// reports ErrServerClosed, so there is nothing to filter out.
+func (s *infoShim) Close() error {
+	err := s.srv.Close()
+	<-s.done
+	return err
+}
diff --git a/localembed/infoshim_test.go b/localembed/infoshim_test.go
new file mode 100644
index 0000000..0d073bf
--- /dev/null
+++ b/localembed/infoshim_test.go
@@ -0,0 +1,128 @@
+package localembed
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func testShimPin() (Model, Pin) {
+	const sha = "0123456789abcdef0123456789abcdef01234567"
+	m := Model{RepoID: "org/model", Revision: sha}
+	p := Pin{
+		RepoID:     "org/model",
+		CommitHash: sha,
+		RepoInfo:   json.RawMessage(`{"id":"org/model","sha":"` + sha + `","siblings":[]}`),
+	}
+	return m, p
+}
+
+func TestInfoShim_ServesPinnedRevision(t *testing.T) {
+	m, p := testShimPin()
+	shim, err := startInfoShim(m, p)
+	if err != nil {
+		t.Fatalf("startInfoShim: %v", err)
+	}
+	defer func() { _ = shim.Close() }()
+
+	url := shim.URL + "/api/models/org/model/revision/" + p.CommitHash + "?blobs=true"
+	resp, err := http.Get(url) // #nosec G107 -- loopback URL from this test's own shim
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("ReadAll: %v", err)
+	}
+	if string(body) != string(p.RepoInfo) {
+		t.Errorf("body = %s, want the pin's RepoInfo verbatim %s", body, p.RepoInfo)
+	}
+	if ct := resp.Header.Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+}
+
+func TestInfoShim_ServedBytesAreIndependentOfTheCaller(t *testing.T) {
+	// The shim exists because LockedDownload unlinks its destination before
+	// fetching, so what it serves must not be reachable by anyone else.
+	// json.RawMessage is a []byte: `[]byte(p.RepoInfo)` aliases the caller's
+	// array rather than copying it, so without a defensive copy a later write
+	// through the pin would change what the shim serves mid-flight.
+	m, p := testShimPin()
+	original := string(p.RepoInfo)
+	shim, err := startInfoShim(m, p)
+	if err != nil {
+		t.Fatalf("startInfoShim: %v", err)
+	}
+	defer func() { _ = shim.Close() }()
+
+	// Scribble over the caller's copy.
+	for i := range p.RepoInfo {
+		p.RepoInfo[i] = 'X'
+	}
+
+	resp, err := http.Get(shim.URL + "/api/models/org/model/revision/" + p.CommitHash) // #nosec G107 -- loopback URL from this test's own shim
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("ReadAll: %v", err)
+	}
+	if string(body) != original {
+		t.Errorf("body = %s, want %s; the shim is aliasing the caller's buffer", body, original)
+	}
+}
+
+func TestInfoShim_UnknownPathsAre404AndRecorded(t *testing.T) {
+	m, p := testShimPin()
+	shim, err := startInfoShim(m, p)
+	if err != nil {
+		t.Fatalf("startInfoShim: %v", err)
+	}
+	defer func() { _ = shim.Close() }()
+
+	for _, path := range []string{
+		"/org/model/resolve/" + p.CommitHash + "/model.safetensors",
+		"/api/models/org/model/revision/89abcdef0123456789abcdef0123456789abcdef",
+	} {
+		resp, err := http.Get(shim.URL + path) // #nosec G107 -- loopback URL from this test's own shim
+		if err != nil {
+			t.Fatalf("GET %s: %v", path, err)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		if resp.StatusCode != http.StatusNotFound {
+			t.Errorf("GET %s status = %d, want 404", path, resp.StatusCode)
+		}
+		// The body must name what was asked for, so the surfaced error is
+		// actionable rather than a bare HTTP failure.
+		if !strings.Contains(string(body), path) {
+			t.Errorf("404 body %q does not name the requested path %q", body, path)
+		}
+	}
+	missed := shim.missedPaths()
+	if len(missed) != 2 {
+		t.Errorf("missedPaths() = %v, want 2 entries", missed)
+	}
+}
+
+func TestInfoShim_HasReadHeaderTimeout(t *testing.T) {
+	// gosec G112: a server without ReadHeaderTimeout is a Slowloris risk.
+	m, p := testShimPin()
+	shim, err := startInfoShim(m, p)
+	if err != nil {
+		t.Fatalf("startInfoShim: %v", err)
+	}
+	defer func() { _ = shim.Close() }()
+	if shim.srv.ReadHeaderTimeout <= 0 {
+		t.Error("ReadHeaderTimeout is unset")
+	}
+}
diff --git a/localembed/model.go b/localembed/model.go
index 92fb5a5..cc30f5e 100644
--- a/localembed/model.go
+++ b/localembed/model.go
@@ -1,6 +1,7 @@
 package localembed
 
 import (
+	"encoding/json"
 	"fmt"
 	"slices"
 	"strings"
@@ -59,6 +60,97 @@ var standardManifest = []string{
 	"model.safetensors",
 }
 
+// expandManifest augments base with the extra files modulesJSON declares
+// beyond the plain Transformer+Pooling pair, using the sizes and hashes
+// repoInfo already reports.
+//
+// standardManifest — what base is for an unpinned repository id — only covers
+// module 0 (the bare Transformer, path "") and module 1 (1_Pooling). A model
+// such as google/embeddinggemma-300m adds a Dense projection module ("2_Dense")
+// or a Normalize step, each with its own files at "<path>/<name>" inside the
+// same repository; without this, Download reports success while
+// transformer.LoadModel still needs a file that was never fetched, and
+// MissingFiles reports the model ready when it is not (see the
+// pinned-model-revision design doc's "Known limitations"). Widening
+// standardManifest itself was rejected there: every registry entry is
+// hand-verified against exactly the plain set, so this only ever runs for a
+// model discovered from a raw repository id, which has no such guarantee to
+// begin with.
+//
+// Extra files are inserted before base's model.safetensors, if present, so a
+// small metadata file added here still fails fast rather than waiting behind
+// whatever multi-hundred-megabyte download was already in flight — the same
+// reasoning that orders standardManifest itself.
+func expandManifest(modulesJSON, repoInfo []byte, base []ManifestFile) ([]ManifestFile, error) {
+	var modules []struct {
+		Path string `json:"path"`
+	}
+	if err := json.Unmarshal(modulesJSON, &modules); err != nil {
+		return nil, fmt.Errorf("parsing modules.json: %w", err)
+	}
+
+	extraModules := make(map[string]bool)
+	for _, mod := range modules {
+		if mod.Path == "" || mod.Path == "1_Pooling" {
+			continue
+		}
+		extraModules[mod.Path] = true
+	}
+	if len(extraModules) == 0 {
+		return base, nil
+	}
+
+	var info struct {
+		Siblings []struct {
+			RFilename string `json:"rfilename"`
+			Size      int64  `json:"size"`
+			LFS       *struct {
+				SHA256 string `json:"sha256"`
+			} `json:"lfs"`
+		} `json:"siblings"`
+	}
+	if err := json.Unmarshal(repoInfo, &info); err != nil {
+		return nil, fmt.Errorf("parsing repository info: %w", err)
+	}
+
+	known := make(map[string]bool, len(base))
+	for _, f := range base {
+		known[f.Path] = true
+	}
+	var extraFiles []ManifestFile
+	for _, sib := range info.Siblings {
+		if known[sib.RFilename] {
+			continue
+		}
+		dir, _, ok := strings.Cut(sib.RFilename, "/")
+		if !ok || !extraModules[dir] {
+			continue
+		}
+		f := ManifestFile{Path: sib.RFilename, Size: sib.Size}
+		if sib.LFS != nil {
+			f.SHA256 = sib.LFS.SHA256
+		}
+		extraFiles = append(extraFiles, f)
+		known[sib.RFilename] = true
+	}
+	if len(extraFiles) == 0 {
+		return base, nil
+	}
+
+	insertAt := len(base)
+	for i, f := range base {
+		if f.Path == "model.safetensors" {
+			insertAt = i
+			break
+		}
+	}
+	files := make([]ManifestFile, 0, len(base)+len(extraFiles))
+	files = append(files, base[:insertAt]...)
+	files = append(files, extraFiles...)
+	files = append(files, base[insertAt:]...)
+	return files, nil
+}
+
 // DefaultModel is the model used when embedding_model names no other. It is
 // small (133 MB), 384-dimensional, and asymmetric — its query instruction
 // prefix maps onto codamigo's existing index/query embedder split.
diff --git a/localembed/model_internal_test.go b/localembed/model_internal_test.go
index 50904c0..2e70d96 100644
--- a/localembed/model_internal_test.go
+++ b/localembed/model_internal_test.go
@@ -5,6 +5,103 @@ import (
 	"testing"
 )
 
+// baseUnpinnedFiles mirrors what Lookup builds from standardManifest for a
+// raw repository id.
+func baseUnpinnedFiles() []ManifestFile {
+	files := make([]ManifestFile, len(standardManifest))
+	for i, p := range standardManifest {
+		files[i] = ManifestFile{Path: p}
+	}
+	return files
+}
+
+// TestExpandManifest_DiscoversDenseModule is the regression test for
+// google/embeddinggemma-300m: modules.json declares a Dense projection beyond
+// the plain Transformer+Pooling pair, and its files must be added even though
+// standardManifest has never heard of them.
+func TestExpandManifest_DiscoversDenseModule(t *testing.T) {
+	modulesJSON := `[
+		{"idx": 0, "name": "0", "path": "", "type": "sentence_transformers.models.Transformer"},
+		{"idx": 1, "name": "1", "path": "1_Pooling", "type": "sentence_transformers.models.Pooling"},
+		{"idx": 2, "name": "2", "path": "2_Dense", "type": "sentence_transformers.models.Dense"},
+		{"idx": 3, "name": "3", "path": "4_Normalize", "type": "sentence_transformers.models.Normalize"}
+	]`
+	repoInfo := `{"siblings": [
+		{"rfilename": "config.json", "size": 100},
+		{"rfilename": "2_Dense/config.json", "size": 134},
+		{"rfilename": "2_Dense/model.safetensors", "size": 9437272,
+		 "lfs": {"sha256": "c327f2acb00149676ade24a75e11eb6ebbd367f9ee050267ba56829d2979f702"}},
+		{"rfilename": "model.safetensors", "size": 1211486072}
+	]}`
+
+	got, err := expandManifest([]byte(modulesJSON), []byte(repoInfo), baseUnpinnedFiles())
+	if err != nil {
+		t.Fatalf("expandManifest: %v", err)
+	}
+
+	byPath := make(map[string]ManifestFile, len(got))
+	for _, f := range got {
+		byPath[f.Path] = f
+	}
+	for _, want := range []string{"2_Dense/config.json", "2_Dense/model.safetensors"} {
+		if _, ok := byPath[want]; !ok {
+			t.Errorf("expanded manifest is missing %q; got %v", want, got)
+		}
+	}
+	dense := byPath["2_Dense/model.safetensors"]
+	if dense.Size != 9437272 {
+		t.Errorf("2_Dense/model.safetensors Size = %d, want 9437272", dense.Size)
+	}
+	if dense.SHA256 != "c327f2acb00149676ade24a75e11eb6ebbd367f9ee050267ba56829d2979f702" {
+		t.Errorf("2_Dense/model.safetensors SHA256 = %q, want the sibling's lfs.sha256", dense.SHA256)
+	}
+	// 4_Normalize has no siblings of its own in this fixture; it must not
+	// invent a file that was never listed.
+	if _, ok := byPath["4_Normalize/config.json"]; ok {
+		t.Error("expanded manifest invented a file for a module with no matching sibling")
+	}
+
+	// The new files must land before model.safetensors, not after it.
+	denseIdx, weightsIdx := -1, -1
+	for i, f := range got {
+		switch f.Path {
+		case "2_Dense/model.safetensors":
+			denseIdx = i
+		case "model.safetensors":
+			weightsIdx = i
+		}
+	}
+	if denseIdx == -1 || weightsIdx == -1 || denseIdx >= weightsIdx {
+		t.Errorf("2_Dense/model.safetensors (idx %d) must come before model.safetensors (idx %d)", denseIdx, weightsIdx)
+	}
+}
+
+// TestExpandManifest_NoExtraModulesIsNoOp confirms a plain sentence-transformers
+// model — the common case — gets back exactly the manifest it was given.
+func TestExpandManifest_NoExtraModulesIsNoOp(t *testing.T) {
+	modulesJSON := `[
+		{"idx": 0, "name": "0", "path": "", "type": "sentence_transformers.models.Transformer"},
+		{"idx": 1, "name": "1", "path": "1_Pooling", "type": "sentence_transformers.models.Pooling"}
+	]`
+	base := baseUnpinnedFiles()
+	got, err := expandManifest([]byte(modulesJSON), []byte(`{"siblings":[]}`), base)
+	if err != nil {
+		t.Fatalf("expandManifest: %v", err)
+	}
+	if len(got) != len(base) {
+		t.Errorf("expandManifest added files for a model with no extra modules: got %v", got)
+	}
+}
+
+// TestExpandManifest_MalformedModulesJSON asserts a parse failure is reported
+// rather than silently ignored, so a corrupt local file cannot masquerade as
+// "no extra modules".
+func TestExpandManifest_MalformedModulesJSON(t *testing.T) {
+	if _, err := expandManifest([]byte("not json"), []byte(`{}`), baseUnpinnedFiles()); err == nil {
+		t.Error("expandManifest with malformed modules.json = nil error, want error")
+	}
+}
+
 // TestRegistry_EveryEntryIsPinned is the invariant that makes Download a
 // supply-chain check rather than a corruption check: an entry with a missing or
 // invented checksum would either skip verification silently or reject a
diff --git a/localembed/offline_test.go b/localembed/offline_test.go
new file mode 100644
index 0000000..f0f3037
--- /dev/null
+++ b/localembed/offline_test.go
@@ -0,0 +1,264 @@
+package localembed_test
+
+import (
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/ieshan/codamigo/localembed"
+)
+
+// deadEndpoint returns the URL of a server that has already been shut down, so
+// any attempt to reach it fails immediately rather than hanging.
+func deadEndpoint(t *testing.T) string {
+	t.Helper()
+	srv := httptest.NewServer(http.NotFoundHandler())
+	url := srv.URL
+	srv.Close()
+	return url
+}
+
+// TestNew_LoadsWithoutNetwork is the regression test for this whole feature.
+//
+// HF_ENDPOINT is read by hub.New, so pointing it at a closed port means any
+// outbound HuggingFace request fails. New succeeding under that condition
+// proves nothing but the local shim was consulted. Before the pin-and-shim
+// change this failed with "config.json is missing or failed to download from
+// repo" even though every file was already on disk.
+//
+// This test actually loads the model to completion (unlike its siblings in
+// this file, which fail before backend selection), so it runs under both the
+// test-race and bench-localembed CI jobs. It uses Backend: "auto" rather than
+// "go" for the same reason newTestEmbedder skips "go" under -race: the pure-Go
+// backend trips checkptr inside GoMLX's matmul, which aborts the whole test
+// binary under -race. It also quiets the backend-selection log the same way
+// newTestEmbedder does, since it is the only test in this file that reaches it.
+func TestNew_LoadsWithoutNetwork(t *testing.T) {
+	const model = "bge-small-en-v1.5"
+	root := modelsRoot(t, model) // skips when the model is not downloaded
+	t.Setenv("HF_ENDPOINT", deadEndpoint(t))
+
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.DiscardHandler))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	emb, err := localembed.New(localembed.Options{
+		Model:      model,
+		ModelsRoot: root,
+		Backend:    "auto",
+	})
+	if err != nil {
+		t.Fatalf("New with no reachable hub: %v", err)
+	}
+	defer func() { _ = emb.Close() }()
+
+	// Loading is the point, but a real embedding proves the weights and
+	// tokenizer resolved too, not just the config.
+	vec, err := emb.Embed(t.Context(), "hello")
+	if err != nil {
+		t.Fatalf("Embed: %v", err)
+	}
+	if len(vec) != 384 {
+		t.Errorf("Embed returned width %d, want 384 for %s", len(vec), model)
+	}
+}
+
+func TestNew_UnpinnedWithoutPinIsActionable(t *testing.T) {
+	// An unpinned repo id with nothing on disk must say what to run, not
+	// produce an opaque HTTP error.
+	t.Setenv("HF_ENDPOINT", deadEndpoint(t))
+	_, err := localembed.New(localembed.Options{
+		Model:      "org/not-downloaded",
+		ModelsRoot: t.TempDir(),
+		Dimensions: 8,
+	})
+	if err == nil {
+		t.Fatal("New succeeded for a model that is not downloaded")
+	}
+	if !strings.Contains(err.Error(), "download-model") {
+		t.Errorf("error %q does not tell the user how to recover", err)
+	}
+}
+
+// TestNew_FileOutsideTheSnapshotIsNamed covers the shim-404 translation in New.
+//
+// standardManifest is deliberately a subset of what some repositories publish,
+// so a model can pass MissingFiles and still have LoadStore ask for a file the
+// local snapshot never had — a shard of a sharded model, for instance.
+// LoadStore reaches that file through repo.IterFileNames, which iterates the
+// pin's repo_info siblings, so naming an absent .safetensors sibling reproduces
+// the case exactly. Without the translation the user sees a raw HTTP 404
+// quoting a 127.0.0.1:<port> loopback URL.
+//
+// This is the one branch that cannot be reached hermetically. Every file
+// LoadModel probes is in standardManifest, so MissingFiles rejects its absence
+// before the shim is ever consulted; the only requester of a non-manifest file
+// is LoadStore, which runs after GetTokenizer and backend selection and so
+// needs a real tokenizer and real weights. Rather than assert against a
+// synthetic model that never gets that far, this builds a temp models root that
+// symlinks the real snapshot — read-only — and adds the missing sibling there.
+func TestNew_FileOutsideTheSnapshotIsNamed(t *testing.T) {
+	const (
+		model      = "bge-small-en-v1.5"
+		repoID     = "BAAI/bge-small-en-v1.5"
+		flatRepo   = "models--BAAI--bge-small-en-v1.5"
+		absentFile = "model-00002-of-00002.safetensors"
+	)
+	realRoot := modelsRoot(t, model) // skips when the model is not downloaded
+	descriptor, err := localembed.Lookup(model)
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	revision := descriptor.Revision
+
+	// A models root of our own, so the pin we are about to write cannot land in
+	// the user's real cache. The snapshot is a symlink to the real one: the test
+	// only ever reads it, and copying 133 MB per run would be gratuitous.
+	root := t.TempDir()
+	repoDir := filepath.Join(root, model, flatRepo)
+	for _, d := range []string{"info", "blobs", "snapshots"} {
+		if err := os.MkdirAll(filepath.Join(repoDir, d), 0o750); err != nil {
+			t.Fatalf("MkdirAll %s: %v", d, err)
+		}
+	}
+	realSnapshot := filepath.Join(realRoot, model, flatRepo, "snapshots", revision)
+	if err := os.Symlink(realSnapshot, filepath.Join(repoDir, "snapshots", revision)); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+
+	// The siblings list must be faithful for the files the loader resolves
+	// through it — GetTokenizer looks tokenizer.json up in the repo index, not on
+	// disk — so it carries the real manifest plus the one shard that is absent.
+	// That absent shard is what LoadStore reaches for and the shim refuses.
+	siblings := make([]string, 0, len(descriptor.Files)+1)
+	for _, f := range descriptor.Files {
+		siblings = append(siblings, `{"rfilename":"`+f.Path+`"}`)
+	}
+	siblings = append(siblings, `{"rfilename":"`+absentFile+`"}`)
+	repoInfo := `{"id":"` + repoID + `","sha":"` + revision +
+		`","siblings":[` + strings.Join(siblings, ",") + `]}`
+	if err := localembed.WritePin(filepath.Join(root, model), localembed.Pin{
+		RepoID:       repoID,
+		CommitHash:   revision,
+		ResolvedFrom: revision,
+		RepoInfo:     json.RawMessage(repoInfo),
+	}); err != nil {
+		t.Fatalf("WritePin: %v", err)
+	}
+
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.DiscardHandler))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	t.Setenv("HF_ENDPOINT", deadEndpoint(t))
+	emb, err := localembed.New(localembed.Options{
+		Model:      model,
+		ModelsRoot: root,
+		Backend:    "auto",
+	})
+	if err == nil {
+		_ = emb.Close()
+		t.Fatal("New succeeded even though a sibling is absent from the snapshot")
+	}
+	if !errors.Is(err, localembed.ErrModelNotDownloaded) {
+		t.Errorf("New error = %v, want it to wrap ErrModelNotDownloaded", err)
+	}
+	if !strings.Contains(err.Error(), absentFile) {
+		t.Errorf("error %q does not name the absent file %q", err, absentFile)
+	}
+	if !strings.Contains(err.Error(), "download-model") {
+		t.Errorf("error %q does not tell the user how to recover", err)
+	}
+	// The whole point of the translation: no loopback URL in the user's face.
+	if strings.Contains(err.Error(), "127.0.0.1") {
+		t.Errorf("error %q leaks the shim's loopback address", err)
+	}
+}
+
+// TestNew_DamagedPinRepoInfoIsRejected is hermetic: it never touches
+// ~/.codamigo/models.
+//
+// ReadPin only validates CommitHash, never RepoInfo. Without a guard, a pin
+// with a valid hash but empty/mismatched RepoInfo would reach
+// go-huggingface's DownloadInfo, whose LockedDownload unlinks info/<hash>
+// before discovering the replacement is unusable — destroying the on-disk
+// cache the offline path depends on. This asserts New refuses such a pin
+// before anything can unlink that file, and that the pre-existing info file
+// on disk is untouched afterward.
+func TestNew_DamagedPinRepoInfoIsRejected(t *testing.T) {
+	const testHash = "0123456789abcdef0123456789abcdef01234567"
+	tests := []struct {
+		name     string
+		repoInfo json.RawMessage
+	}{
+		{"empty repo_info", nil},
+		{"sha mismatch", json.RawMessage(`{"sha":"ffffffffffffffffffffffffffffffffffffffff","siblings":[]}`)},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			repoDir := filepath.Join(dir, "models--org--damaged")
+			infoDir := filepath.Join(repoDir, "info")
+			if err := os.MkdirAll(infoDir, 0o750); err != nil {
+				t.Fatalf("MkdirAll: %v", err)
+			}
+
+			// A legitimate info file already on disk, as if left over from a
+			// previous successful load. If the guard regresses, go-huggingface
+			// would unlink and try to rewrite this before failing offline.
+			goodInfo := `{"id":"org/damaged","sha":"` + testHash + `","siblings":[]}`
+			infoPath := filepath.Join(infoDir, "main")
+			if err := os.WriteFile(infoPath, []byte(goodInfo), 0o600); err != nil {
+				t.Fatalf("WriteFile info: %v", err)
+			}
+
+			snapshot := filepath.Join(repoDir, "snapshots", testHash)
+			if err := os.MkdirAll(filepath.Join(snapshot, "1_Pooling"), 0o750); err != nil {
+				t.Fatalf("MkdirAll snapshot: %v", err)
+			}
+			for _, f := range []string{
+				"config.json", "config_sentence_transformers.json", "modules.json",
+				"tokenizer.json", "tokenizer_config.json", "1_Pooling/config.json", "model.safetensors",
+			} {
+				if err := os.WriteFile(filepath.Join(snapshot, f), []byte("{}"), 0o600); err != nil {
+					t.Fatalf("WriteFile %s: %v", f, err)
+				}
+			}
+
+			if err := localembed.WritePin(dir, localembed.Pin{
+				RepoID:       "org/damaged",
+				CommitHash:   testHash,
+				ResolvedFrom: "main",
+				RepoInfo:     tt.repoInfo,
+			}); err != nil {
+				t.Fatalf("WritePin: %v", err)
+			}
+
+			_, err := localembed.New(localembed.Options{
+				Model:      "org/damaged",
+				ModelsRoot: dir,
+				Dimensions: 8,
+			})
+			if !errors.Is(err, localembed.ErrModelNotDownloaded) {
+				t.Fatalf("New error = %v, want ErrModelNotDownloaded", err)
+			}
+			if !strings.Contains(err.Error(), "download-model") {
+				t.Errorf("error %q does not tell the user how to recover", err)
+			}
+
+			got, err := os.ReadFile(infoPath)
+			if err != nil {
+				t.Fatalf("info file missing after New: %v", err)
+			}
+			if string(got) != goodInfo {
+				t.Errorf("info file changed by a rejected load: got %q, want %q", got, goodInfo)
+			}
+		})
+	}
+}
diff --git a/localembed/pin.go b/localembed/pin.go
new file mode 100644
index 0000000..829ad44
--- /dev/null
+++ b/localembed/pin.go
@@ -0,0 +1,204 @@
+package localembed
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// pinFileName is the pin file's name. It lives directly under ModelDir rather
+// than inside the models--<id> tree, because everything below ModelDir belongs
+// to go-huggingface (see the layout comment in cache.go).
+const pinFileName = "codamigo-pin.json"
+
+// Pin records the exact upstream revision a model directory holds, so loading
+// the model needs no network round trip to discover it.
+//
+// RepoInfo is the RepoInfo JSON as it arrived from HuggingFace, semantically
+// preserved (compacted, HTML-escaped by json.Marshal) rather than byte-for-byte,
+// because [startInfoShim] serves it straight back to go-huggingface, which must
+// be able to unmarshal it into its own hub.RepoInfo. Storing our own copy is not
+// redundancy: go-huggingface's LockedDownload deletes its info/<revision> file
+// before re-fetching it, so a shim reading that file would be reading something
+// that had just been unlinked.
+type Pin struct {
+	RepoID string `json:"repo_id"`
+	// CommitHash is the resolved 40-hex git commit the snapshot directory is
+	// named after.
+	CommitHash string `json:"commit_hash"`
+	// ResolvedFrom is the revision that was asked for, "main" for an unpinned
+	// model. Kept for diagnostics: it is what distinguishes "pinned upstream"
+	// from "whatever main happened to be".
+	ResolvedFrom string `json:"resolved_from"`
+	// ResolvedAt is when download-model last consulted upstream.
+	ResolvedAt time.Time `json:"resolved_at"`
+	// Dimensions is the model's hidden size, recorded so download-model can
+	// print a real embedding_dimensions value. Display only: it is never
+	// consulted at load time.
+	Dimensions int             `json:"dimensions,omitempty"`
+	RepoInfo   json.RawMessage `json:"repo_info"`
+}
+
+// PinPath returns the pin file's path for a model directory.
+func PinPath(modelDir string) string {
+	return filepath.Join(modelDir, pinFileName)
+}
+
+// WritePin writes the pin file, replacing any existing one.
+func WritePin(modelDir string, p Pin) error {
+	if modelDir == "" {
+		return errors.New("model directory must not be empty")
+	}
+	body, err := json.Marshal(p)
+	if err != nil {
+		return fmt.Errorf("encoding pin for %s: %w", p.RepoID, err)
+	}
+	if err := os.WriteFile(PinPath(modelDir), body, 0o600); err != nil {
+		return fmt.Errorf("writing pin for %s: %w", p.RepoID, err)
+	}
+	return nil
+}
+
+// ReadPin reads the pin file.
+//
+// Absent, unreadable, unparseable and semantically unusable files all return
+// [ErrNoPin] rather than distinct errors, because every caller treats them
+// identically: fall through to deriving the revision from disk.
+func ReadPin(modelDir string) (Pin, error) {
+	// #nosec G304 -- modelDir is derived from the configured models root, not external input
+	body, err := os.ReadFile(PinPath(modelDir))
+	if err != nil {
+		return Pin{}, fmt.Errorf("%w: %s: %w", ErrNoPin, PinPath(modelDir), err)
+	}
+	var p Pin
+	if err := json.Unmarshal(body, &p); err != nil {
+		return Pin{}, fmt.Errorf("%w: %s is not valid JSON: %w", ErrNoPin, PinPath(modelDir), err)
+	}
+	if !isCommitHash(p.CommitHash) {
+		return Pin{}, fmt.Errorf("%w: %s has no valid commit_hash", ErrNoPin, PinPath(modelDir))
+	}
+	return p, nil
+}
+
+// isCommitHash reports whether s is a full 40-character hex git object id.
+// Anything shorter is ambiguous and anything else is not a revision at all.
+func isCommitHash(s string) bool {
+	if len(s) != 40 {
+		return false
+	}
+	for _, r := range s {
+		switch {
+		case r >= '0' && r <= '9', r >= 'a' && r <= 'f':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+// derivePin reconstructs a pin from what go-huggingface already left on disk,
+// for a model directory downloaded before pin files existed. It reads the info
+// file for the requested revision, takes its "sha", and confirms a snapshot of
+// that name is actually present.
+//
+// The info file's bytes become the pin's RepoInfo. They are read here, before
+// the shim starts and before any load begins, which is what keeps them safe
+// from LockedDownload unlinking the file later.
+func derivePin(modelDir string, m Model) (Pin, error) {
+	rev := m.Revision
+	if rev == "" {
+		rev = "main"
+	}
+	repoDir := filepath.Join(modelDir, flatRepoDir(m.RepoID))
+	infoPath := filepath.Join(repoDir, "info", rev)
+	// #nosec G304 -- infoPath is built from the configured models root and the model's own repo id
+	body, err := os.ReadFile(infoPath)
+	if err != nil {
+		return Pin{}, fmt.Errorf("%w: %s has no pin file and no cached info at %s. "+
+			"Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, m.DisplayName(), infoPath, m.DisplayName())
+	}
+	var meta struct {
+		SHA string `json:"sha"`
+	}
+	if err := json.Unmarshal(body, &meta); err != nil {
+		return Pin{}, fmt.Errorf("%w: cached info at %s is not valid JSON: %w. "+
+			"Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, infoPath, err, m.DisplayName())
+	}
+	if !isCommitHash(meta.SHA) {
+		return Pin{}, fmt.Errorf("%w: cached info at %s has no valid sha. "+
+			"Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, infoPath, m.DisplayName())
+	}
+	snapshot := filepath.Join(repoDir, "snapshots", meta.SHA)
+	if info, err := os.Stat(snapshot); err != nil || !info.IsDir() {
+		return Pin{}, fmt.Errorf("%w: cached info names revision %s but %s is not present. "+
+			"Run: codamigo download-model --model %s",
+			ErrModelNotDownloaded, meta.SHA, snapshot, m.DisplayName())
+	}
+	return Pin{
+		RepoID:       m.RepoID,
+		CommitHash:   meta.SHA,
+		ResolvedFrom: rev,
+		RepoInfo:     body,
+	}, nil
+}
+
+// ResolvePin returns m with Revision set to the concrete commit hash the model
+// directory actually holds, together with the pin that decided it.
+//
+// A registry model keeps its compiled-in Revision: that hash is the
+// supply-chain pin, so a pin file must never be able to redirect it. A pin file
+// that contradicts it means the directory and the binary disagree, which is
+// reported rather than silently resolved in either direction.
+func ResolvePin(modelDir string, m Model) (Model, Pin, error) {
+	p, err := ReadPin(modelDir)
+	if err != nil {
+		if p, err = derivePin(modelDir, m); err != nil {
+			return Model{}, Pin{}, err
+		}
+	}
+	if m.Registered {
+		if p.CommitHash != m.Revision {
+			return Model{}, Pin{}, fmt.Errorf(
+				"%s is pinned to revision %s but %s holds %s. "+
+					"Run: codamigo download-model --model %s --force",
+				m.DisplayName(), m.Revision, modelDir, p.CommitHash, m.DisplayName())
+		}
+		return m, p, nil
+	}
+	m.Revision = p.CommitHash
+	m.Files = expandManifestFromSnapshot(modelDir, m, p)
+	return m, p, nil
+}
+
+// expandManifestFromSnapshot is the load-time twin of [expandUnpinnedManifest]:
+// no network access is available here, so it reads modules.json from the
+// snapshot directory Revision now names, instead of fetching it, and reuses
+// the repository info the pin already carries.
+//
+// Any failure to read or parse falls back to m.Files unchanged rather than
+// failing ResolvePin outright: an unreadable or absent modules.json is exactly
+// what [MissingFiles] already reports on the base manifest, and a malformed
+// repoInfo is diagnosed later, when the caller actually needs it, rather than
+// here where the only consequence would be an incomplete manifest.
+func expandManifestFromSnapshot(modelDir string, m Model, p Pin) []ManifestFile {
+	snapshot, err := SnapshotDir(modelDir, m)
+	if err != nil {
+		return m.Files
+	}
+	// #nosec G304 -- path is inside the model directory ResolvePin was asked about
+	modulesJSON, err := os.ReadFile(filepath.Join(snapshot, "modules.json"))
+	if err != nil {
+		return m.Files
+	}
+	expanded, err := expandManifest(modulesJSON, p.RepoInfo, m.Files)
+	if err != nil {
+		return m.Files
+	}
+	return expanded
+}
diff --git a/localembed/pin_test.go b/localembed/pin_test.go
new file mode 100644
index 0000000..f1f613b
--- /dev/null
+++ b/localembed/pin_test.go
@@ -0,0 +1,321 @@
+package localembed_test
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/ieshan/codamigo/localembed"
+)
+
+const testHash = "0123456789abcdef0123456789abcdef01234567"
+
+func TestPin_RoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	want := localembed.Pin{
+		RepoID:       "org/model",
+		CommitHash:   testHash,
+		ResolvedFrom: "main",
+		ResolvedAt:   time.Date(2026, 8, 7, 12, 0, 0, 0, time.UTC),
+		Dimensions:   768,
+		RepoInfo:     json.RawMessage(`{"sha":"` + testHash + `","siblings":[]}`),
+	}
+	if err := localembed.WritePin(dir, want); err != nil {
+		t.Fatalf("WritePin: %v", err)
+	}
+	got, err := localembed.ReadPin(dir)
+	if err != nil {
+		t.Fatalf("ReadPin: %v", err)
+	}
+	if got.CommitHash != want.CommitHash {
+		t.Errorf("CommitHash = %q, want %q", got.CommitHash, want.CommitHash)
+	}
+	if got.RepoID != want.RepoID {
+		t.Errorf("RepoID = %q, want %q", got.RepoID, want.RepoID)
+	}
+	if got.ResolvedFrom != want.ResolvedFrom {
+		t.Errorf("ResolvedFrom = %q, want %q", got.ResolvedFrom, want.ResolvedFrom)
+	}
+	if got.Dimensions != want.Dimensions {
+		t.Errorf("Dimensions = %d, want %d", got.Dimensions, want.Dimensions)
+	}
+	if !got.ResolvedAt.Equal(want.ResolvedAt) {
+		t.Errorf("ResolvedAt = %v, want %v", got.ResolvedAt, want.ResolvedAt)
+	}
+	// RepoInfo must round-trip: this fixture is already compact JSON with no
+	// characters json.Marshal would HTML-escape, so byte-for-byte is the
+	// expected outcome here (see the RepoInfo field doc for the general case).
+	if string(got.RepoInfo) != string(want.RepoInfo) {
+		t.Errorf("RepoInfo = %s, want %s", got.RepoInfo, want.RepoInfo)
+	}
+}
+
+func TestPin_WriteUsesRestrictivePermissions(t *testing.T) {
+	dir := t.TempDir()
+	p := localembed.Pin{RepoID: "org/model", CommitHash: testHash, RepoInfo: json.RawMessage(`{}`)}
+	if err := localembed.WritePin(dir, p); err != nil {
+		t.Fatalf("WritePin: %v", err)
+	}
+	info, err := os.Stat(localembed.PinPath(dir))
+	if err != nil {
+		t.Fatalf("Stat: %v", err)
+	}
+	if perm := info.Mode().Perm(); perm != 0o600 {
+		t.Errorf("permissions = %o, want 600", perm)
+	}
+}
+
+func TestPin_ReadAbsentIsErrNoPin(t *testing.T) {
+	if _, err := localembed.ReadPin(t.TempDir()); !errors.Is(err, localembed.ErrNoPin) {
+		t.Errorf("ReadPin on empty dir = %v, want ErrNoPin", err)
+	}
+}
+
+func TestPin_ReadCorruptIsErrNoPin(t *testing.T) {
+	// A truncated or garbage pin file must read as "no pin" so callers fall
+	// through to derivation rather than failing outright.
+	for name, body := range map[string]string{
+		"not json":     "{{{",
+		"empty object": "{}",
+		"short hash":   `{"repo_id":"org/model","commit_hash":"abc","repo_info":{}}`,
+		"non-hex hash": `{"repo_id":"org/model","commit_hash":"zzzz56789abcdef0123456789abcdef01234567","repo_info":{}}`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			if err := os.WriteFile(filepath.Join(dir, "codamigo-pin.json"), []byte(body), 0o600); err != nil {
+				t.Fatalf("WriteFile: %v", err)
+			}
+			if _, err := localembed.ReadPin(dir); !errors.Is(err, localembed.ErrNoPin) {
+				t.Errorf("ReadPin = %v, want ErrNoPin", err)
+			}
+		})
+	}
+}
+
+// writeDerivable lays out a model directory the way go-huggingface leaves one:
+// an info file named after the requested revision, whose "sha" names an
+// existing snapshot directory. No pin file.
+func writeDerivable(t *testing.T, dir, requestedRev, sha string) {
+	t.Helper()
+	repoDir := filepath.Join(dir, "models--org--model")
+	if err := os.MkdirAll(filepath.Join(repoDir, "info"), 0o750); err != nil {
+		t.Fatalf("MkdirAll info: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join(repoDir, "snapshots", sha), 0o750); err != nil {
+		t.Fatalf("MkdirAll snapshots: %v", err)
+	}
+	body := `{"id":"org/model","sha":"` + sha + `","siblings":[]}`
+	if err := os.WriteFile(filepath.Join(repoDir, "info", requestedRev), []byte(body), 0o600); err != nil {
+		t.Fatalf("WriteFile info: %v", err)
+	}
+}
+
+func unpinnedTestModel() localembed.Model {
+	return localembed.Model{
+		RepoID:   "org/model",
+		Revision: "main",
+		Files:    []localembed.ManifestFile{{Path: "config.json"}},
+	}
+}
+
+func registeredTestModel(revision string) localembed.Model {
+	return localembed.Model{
+		Name:       "test-model",
+		RepoID:     "org/model",
+		Revision:   revision,
+		Registered: true,
+		Files:      []localembed.ManifestFile{{Path: "config.json"}},
+	}
+}
+
+func TestResolvePin_UnpinnedUsesPinFile(t *testing.T) {
+	dir := t.TempDir()
+	if err := localembed.WritePin(dir, localembed.Pin{
+		RepoID: "org/model", CommitHash: testHash, ResolvedFrom: "main",
+		RepoInfo: json.RawMessage(`{"sha":"` + testHash + `"}`),
+	}); err != nil {
+		t.Fatalf("WritePin: %v", err)
+	}
+	got, pin, err := localembed.ResolvePin(dir, unpinnedTestModel())
+	if err != nil {
+		t.Fatalf("ResolvePin: %v", err)
+	}
+	if got.Revision != testHash {
+		t.Errorf("Revision = %q, want %q", got.Revision, testHash)
+	}
+	if pin.CommitHash != testHash {
+		t.Errorf("pin.CommitHash = %q, want %q", pin.CommitHash, testHash)
+	}
+}
+
+func TestResolvePin_UnpinnedDerivesWhenNoPinFile(t *testing.T) {
+	// The migration path: an existing install has info/main and a snapshot but
+	// no pin file, and must resolve with no network and no re-download.
+	dir := t.TempDir()
+	writeDerivable(t, dir, "main", testHash)
+
+	got, pin, err := localembed.ResolvePin(dir, unpinnedTestModel())
+	if err != nil {
+		t.Fatalf("ResolvePin: %v", err)
+	}
+	if got.Revision != testHash {
+		t.Errorf("Revision = %q, want %q", got.Revision, testHash)
+	}
+	if len(pin.RepoInfo) == 0 {
+		t.Error("derived pin has empty RepoInfo; the shim would have nothing to serve")
+	}
+	// Derivation must not write anything: the load path stays read-only.
+	if _, err := os.Stat(localembed.PinPath(dir)); !errors.Is(err, os.ErrNotExist) {
+		t.Errorf("derivation wrote a pin file; Stat err = %v, want not-exist", err)
+	}
+}
+
+func TestResolvePin_DeriveRejectsShaWithoutSnapshot(t *testing.T) {
+	// An info file claiming a revision we never actually downloaded is not a
+	// usable pin.
+	dir := t.TempDir()
+	repoDir := filepath.Join(dir, "models--org--model")
+	if err := os.MkdirAll(filepath.Join(repoDir, "info"), 0o750); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	body := `{"sha":"` + testHash + `"}`
+	if err := os.WriteFile(filepath.Join(repoDir, "info", "main"), []byte(body), 0o600); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+	if _, _, err := localembed.ResolvePin(dir, unpinnedTestModel()); !errors.Is(err, localembed.ErrModelNotDownloaded) {
+		t.Errorf("ResolvePin = %v, want ErrModelNotDownloaded", err)
+	}
+}
+
+func TestResolvePin_NothingResolvable(t *testing.T) {
+	if _, _, err := localembed.ResolvePin(t.TempDir(), unpinnedTestModel()); !errors.Is(err, localembed.ErrModelNotDownloaded) {
+		t.Errorf("ResolvePin on empty dir = %v, want ErrModelNotDownloaded", err)
+	}
+}
+
+func TestResolvePin_RegistryRevisionWins(t *testing.T) {
+	// A registry model's compiled-in revision is the supply-chain pin. Even a
+	// well-formed pin file agreeing with it must not become the source of truth.
+	dir := t.TempDir()
+	if err := localembed.WritePin(dir, localembed.Pin{
+		RepoID: "org/model", CommitHash: testHash, ResolvedFrom: testHash,
+		RepoInfo: json.RawMessage(`{"sha":"` + testHash + `"}`),
+	}); err != nil {
+		t.Fatalf("WritePin: %v", err)
+	}
+	got, _, err := localembed.ResolvePin(dir, registeredTestModel(testHash))
+	if err != nil {
+		t.Fatalf("ResolvePin: %v", err)
+	}
+	if got.Revision != testHash {
+		t.Errorf("Revision = %q, want the compiled-in %q", got.Revision, testHash)
+	}
+}
+
+// TestResolvePin_DiscoversDenseModuleFromDisk is the offline twin of
+// TestDownload_DiscoversExtraModuleFiles: a snapshot downloaded before this
+// fix, or downloaded elsewhere, already has modules.json declaring a Dense
+// projection on disk. ResolvePin must fold in those extra files so
+// MissingFiles reports the truth — ready when the Dense files are present,
+// still missing when they are not — instead of the base manifest's blind spot.
+func TestResolvePin_DiscoversDenseModuleFromDisk(t *testing.T) {
+	repoDir := "models--org--model"
+	modulesJSON := `[
+		{"idx": 0, "name": "0", "path": "", "type": "sentence_transformers.models.Transformer"},
+		{"idx": 1, "name": "1", "path": "1_Pooling", "type": "sentence_transformers.models.Pooling"},
+		{"idx": 2, "name": "2", "path": "2_Dense", "type": "sentence_transformers.models.Dense"}
+	]`
+	repoInfo := `{"sha":"` + testHash + `","siblings":[
+		{"rfilename":"2_Dense/config.json","size":4},
+		{"rfilename":"2_Dense/model.safetensors","size":4}
+	]}`
+
+	setup := func(t *testing.T, dir string, writeDenseFiles bool) {
+		t.Helper()
+		snapshot := filepath.Join(dir, repoDir, "snapshots", testHash)
+		if err := os.MkdirAll(snapshot, 0o750); err != nil {
+			t.Fatalf("MkdirAll: %v", err)
+		}
+		if err := os.WriteFile(filepath.Join(snapshot, "modules.json"), []byte(modulesJSON), 0o600); err != nil {
+			t.Fatalf("WriteFile modules.json: %v", err)
+		}
+		// unpinnedTestModel's base manifest is just config.json; put it on disk
+		// too, so the only thing under test is whether the Dense discovery
+		// changes the verdict.
+		if err := os.WriteFile(filepath.Join(snapshot, "config.json"), []byte("test"), 0o600); err != nil {
+			t.Fatalf("WriteFile config.json: %v", err)
+		}
+		if err := localembed.WritePin(dir, localembed.Pin{
+			RepoID: "org/model", CommitHash: testHash, ResolvedFrom: "main",
+			RepoInfo: json.RawMessage(repoInfo),
+		}); err != nil {
+			t.Fatalf("WritePin: %v", err)
+		}
+		if !writeDenseFiles {
+			return
+		}
+		if err := os.MkdirAll(filepath.Join(snapshot, "2_Dense"), 0o750); err != nil {
+			t.Fatalf("MkdirAll 2_Dense: %v", err)
+		}
+		for _, name := range []string{"config.json", "model.safetensors"} {
+			if err := os.WriteFile(filepath.Join(snapshot, "2_Dense", name), []byte("test"), 0o600); err != nil {
+				t.Fatalf("WriteFile 2_Dense/%s: %v", name, err)
+			}
+		}
+	}
+
+	t.Run("dense files present", func(t *testing.T) {
+		dir := t.TempDir()
+		setup(t, dir, true)
+		resolved, _, err := localembed.ResolvePin(dir, unpinnedTestModel())
+		if err != nil {
+			t.Fatalf("ResolvePin: %v", err)
+		}
+		missing, err := localembed.MissingFiles(dir, resolved)
+		if err != nil {
+			t.Fatalf("MissingFiles: %v", err)
+		}
+		if len(missing) != 0 {
+			t.Errorf("MissingFiles = %v, want none once the Dense files are on disk", missing)
+		}
+	})
+
+	t.Run("dense files absent", func(t *testing.T) {
+		dir := t.TempDir()
+		setup(t, dir, false)
+		resolved, _, err := localembed.ResolvePin(dir, unpinnedTestModel())
+		if err != nil {
+			t.Fatalf("ResolvePin: %v", err)
+		}
+		missing, err := localembed.MissingFiles(dir, resolved)
+		if err != nil {
+			t.Fatalf("MissingFiles: %v", err)
+		}
+		if !slices.Contains(missing, "2_Dense/config.json") || !slices.Contains(missing, "2_Dense/model.safetensors") {
+			t.Errorf("MissingFiles = %v, want it to name the missing Dense files", missing)
+		}
+	})
+}
+
+func TestResolvePin_RegistryMismatchIsRefused(t *testing.T) {
+	const otherHash = "89abcdef0123456789abcdef0123456789abcdef"
+	dir := t.TempDir()
+	if err := localembed.WritePin(dir, localembed.Pin{
+		RepoID: "org/model", CommitHash: otherHash, ResolvedFrom: "main",
+		RepoInfo: json.RawMessage(`{"sha":"` + otherHash + `"}`),
+	}); err != nil {
+		t.Fatalf("WritePin: %v", err)
+	}
+	_, _, err := localembed.ResolvePin(dir, registeredTestModel(testHash))
+	if err == nil {
+		t.Fatal("ResolvePin succeeded with a pin that contradicts the compiled-in revision")
+	}
+	if !strings.Contains(err.Error(), "download-model") {
+		t.Errorf("error %q does not tell the user how to recover", err)
+	}
+}