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/serialize.go

@@ -34,12 +34,12 @@ func (m *manifest) generate() error {
 	}
 	dat, err := proto.MarshalOptions{Deterministic: true}.Marshal(m.pbOuter)
 	if err != nil {
-		return err
+		return fmt.Errorf("serialize: marshal outer: %w", err)
 	}
 	m.output = bytes.NewBuffer([]byte(MAGIC))
 	_, err = m.output.Write(dat)
 	if err != nil {
-		return err
+		return fmt.Errorf("serialize: write output: %w", err)
 	}
 	return nil
 }
@@ -60,18 +60,18 @@ func (m *manifest) generateOuter() error {
 
 	innerData, err := proto.MarshalOptions{Deterministic: true}.Marshal(m.pbInner)
 	if err != nil {
-		return err
+		return fmt.Errorf("serialize: marshal inner: %w", err)
 	}
 
 	// Compress the inner data
 	idc := new(bytes.Buffer)
 	zw, err := zstd.NewWriter(idc, zstd.WithEncoderLevel(zstd.SpeedBestCompression))
 	if err != nil {
-		return err
+		return fmt.Errorf("serialize: create compressor: %w", err)
 	}
 	_, err = zw.Write(innerData)
 	if err != nil {
-		return err
+		return fmt.Errorf("serialize: compress: %w", err)
 	}
 	_ = zw.Close()
 
@@ -80,7 +80,7 @@ func (m *manifest) generateOuter() error {
 	// Hash the compressed data for integrity verification before decompression
 	h := sha256.New()
 	if _, err := h.Write(compressedData); err != nil {
-		return err
+		return fmt.Errorf("serialize: hash write: %w", err)
 	}
 	sha256Hash := h.Sum(nil)