1.0 quality polish — code review, tests, bug fixes, documentation (#32)

Comprehensive quality pass targeting 1.0 release:

- Code review and refactoring
- Fix open bugs (#14, #16, #23)
- Expand test coverage
- Lint clean
- README update with build instructions (#9)
- Documentation improvements

Branched from `next` (active dev branch).

Reviewed-on: #32
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

mfer/checker_test.go

@@ -3,6 +3,7 @@ package mfer
 import (
 	"bytes"
 	"context"
+	"fmt"
 	"testing"
 	"time"
 
@@ -452,6 +453,61 @@ func TestCheckMissingFileDetectedWithoutFallback(t *testing.T) {
 	assert.Equal(t, 0, statusCounts[StatusError], "no files should be ERROR")
 }
 
+func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
+	// Regression test for #16: FindExtraFiles should not report dotfiles
+	// or the manifest file itself as extra files.
+	fs := afero.NewMemMapFs()
+	files := map[string][]byte{
+		"file1.txt": []byte("in manifest"),
+	}
+	createTestManifest(t, fs, "/data/.index.mf", files)
+	createFilesOnDisk(t, fs, "/data", files)
+
+	// Add dotfiles and manifest file on disk
+	require.NoError(t, afero.WriteFile(fs, "/data/.hidden", []byte("dotfile"), 0o644))
+	require.NoError(t, fs.MkdirAll("/data/.git", 0o755))
+	require.NoError(t, afero.WriteFile(fs, "/data/.git/config", []byte("git config"), 0o644))
+
+	chk, err := NewChecker("/data/.index.mf", "/data", fs)
+	require.NoError(t, err)
+
+	results := make(chan Result, 10)
+	err = chk.FindExtraFiles(context.Background(), results)
+	require.NoError(t, err)
+
+	var extras []Result
+	for r := range results {
+		extras = append(extras, r)
+	}
+
+	// Should report NO extra files — dotfiles and manifest should be skipped
+	assert.Empty(t, extras, "FindExtraFiles should not report dotfiles or manifest file as extra; got: %v", extras)
+}
+
+func TestFindExtraFilesSkipsManifestFile(t *testing.T) {
+	// The manifest file itself should never be reported as extra
+	fs := afero.NewMemMapFs()
+	files := map[string][]byte{
+		"file1.txt": []byte("content"),
+	}
+	createTestManifest(t, fs, "/data/index.mf", files)
+	createFilesOnDisk(t, fs, "/data", files)
+
+	chk, err := NewChecker("/data/index.mf", "/data", fs)
+	require.NoError(t, err)
+
+	results := make(chan Result, 10)
+	err = chk.FindExtraFiles(context.Background(), results)
+	require.NoError(t, err)
+
+	var extras []Result
+	for r := range results {
+		extras = append(extras, r)
+	}
+
+	assert.Empty(t, extras, "manifest file should not be reported as extra; got: %v", extras)
+}
+
 func TestCheckEmptyManifest(t *testing.T) {
 	fs := afero.NewMemMapFs()
 	// Create manifest with no files
@@ -473,3 +529,40 @@ func TestCheckEmptyManifest(t *testing.T) {
 	}
 	assert.Equal(t, 0, count)
 }
+
+func TestCheckProgressRateLimited(t *testing.T) {
+	// Create many small files - progress should be rate-limited, not one per file.
+	// With rate-limiting to once per second, we should get far fewer progress
+	// updates than files (plus one final update).
+	fs := afero.NewMemMapFs()
+	files := make(map[string][]byte, 100)
+	for i := 0; i < 100; i++ {
+		name := fmt.Sprintf("file%03d.txt", i)
+		files[name] = []byte("content")
+	}
+	createTestManifest(t, fs, "/manifest.mf", files)
+	createFilesOnDisk(t, fs, "/data", files)
+
+	chk, err := NewChecker("/manifest.mf", "/data", fs)
+	require.NoError(t, err)
+
+	results := make(chan Result, 200)
+	progress := make(chan CheckStatus, 200)
+	err = chk.Check(context.Background(), results, progress)
+	require.NoError(t, err)
+
+	// Drain results
+	for range results {
+	}
+
+	// Count progress updates
+	var progressCount int
+	for range progress {
+		progressCount++
+	}
+
+	// Should be far fewer than 100 (rate-limited to once per second)
+	// At minimum we get the final update
+	assert.GreaterOrEqual(t, progressCount, 1, "should get at least the final progress update")
+	assert.Less(t, progressCount, 100, "progress should be rate-limited, not one per file")
+}