docs: correct Nil processor description, errors.As guidance, and file structure

[MasterOfBinary]

Summary

Fixes documentation drift found in a full-repo review.

Changes

• Nil processor (HIGH drift): CLAUDE.md, AGENTS.md, and README.md described it as a benchmarking pass-through, but it actually sleeps for a configurable Duration (and can mark items cancelled). Corrected to match processor/doc.go.
• errors.As guidance: clarified that the engine wraps errors as pointers, so callers must target the pointer type — var se *batch.SourceError; errors.As(err, &se). The value-target form does not match.
• File structure: refreshed CLAUDE.md's stale layout to reflect the actual tree (config.go, errors.go, constants.go, helpers.go, the example_*_test.go files, concrete processor/source files).
• doc.go nits: removed a misleading // Output: marker from the root package doc comment; added a concurrency caution to the source/doc.go example (data and errors should be consumed concurrently).

Testing

go vet ./..., go build ./..., and go test ./... all pass (documentation and package-doc comments only).

Backwards compatibility

Documentation only.

---

Part of a 5-PR set from a full-repo review; file-disjoint and independently mergeable in any order.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates documentation across several files (AGENTS.md, CLAUDE.md, README.md, doc.go, and source/doc.go) to clarify file structures, describe the Nil processor's timing behavior, warn about concurrent channel consumption, and explain how to use errors.As with pointer types. The feedback suggests simplifying the explanation of errors.As in AGENTS.md and CLAUDE.md to avoid non-idiomatic Go patterns like using new() with a pointer type.

[gemini-code-assist]

The parenthetical (equivalently errors.As(err, new(*batch.SourceError))) is technically correct but highly non-idiomatic in Go.

In Go, the standard and idiomatic way to use errors.As with a pointer type is:

var se *batch.SourceError
errors.As(err, &se)

Using new(*batch.SourceError) is rarely seen and can confuse readers because it returns a double pointer (**batch.SourceError), requiring extra dereferencing to access the error fields.

Additionally, the phrase "The engine wraps errors as pointers" could be more precisely stated as "The engine returns errors as pointers" or "The engine instantiates errors as pointers", since "wrapping" in Go errors typically refers to the Unwrap chain rather than pointer vs. value types.

Consider simplifying and refining this sentence:

- Use `errors.As` to check error types (SourceError, ProcessorError). The engine returns errors as pointers (`*SourceError`, `*ProcessorError`), so `errors.As` must target the pointer type — e.g., `var se *batch.SourceError; errors.As(err, &se)`. A value-target such as `var se batch.SourceError; errors.As(err, &se)` will not match.

[gemini-code-assist]

The parenthetical (equivalently errors.As(err, new(*batch.SourceError))) is technically correct but highly non-idiomatic in Go.

In Go, the standard and idiomatic way to use errors.As with a pointer type is:

var se *batch.SourceError
errors.As(err, &se)

Using new(*batch.SourceError) is rarely seen and can confuse readers because it returns a double pointer (**batch.SourceError), requiring extra dereferencing to access the error fields.

Additionally, the phrase "The engine wraps errors as pointers" could be more precisely stated as "The engine returns errors as pointers" or "The engine instantiates errors as pointers", since "wrapping" in Go errors typically refers to the Unwrap chain rather than pointer vs. value types.

Consider simplifying and refining this sentence:

- Use `errors.As` to check error types (SourceError, ProcessorError). The engine returns errors as pointers (`*SourceError`, `*ProcessorError`), so `errors.As` must target the pointer type — e.g., `var se *batch.SourceError; errors.As(err, &se)`. A value-target such as `var se batch.SourceError; errors.As(err, &se)` will not match.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.73%. Comparing base (ba2a756) to head (849789b).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #68   +/-   ##
=======================================
  Coverage   96.73%   96.73%           
=======================================
  Files          12       12           
  Lines         368      368           
=======================================
  Hits          356      356           
  Misses          9        9           
  Partials        3        3           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.