[Maintenance] Update dependencies and enhance documentation

[Zenithar]

Summary

This maintenance PR updates CI/CD dependencies (golangci-lint, gotestsum), removes the deprecated golangci-lint configuration file, fixes linter findings, significantly expands project documentation, and adds comprehensive LLM context documentation. The changes improve code quality, modernise the tooling stack, and enhance developer experience.

Changes

Infrastructure

• Updated golangci-lint GitHub Action from v6.5.2 to v9.0.0
• Updated golangci-lint from v1.64.8 to v2.6.1
• Updated gotestsum from 1.12.1 to 1.13.0 across all test jobs
• Removed .golangci.yml configuration file (now using defaults)
• Updated Nix flake dependencies

Documentation

• Significantly expanded README.md with:
  • Comprehensive feature overview with emojis and badges
  • Detailed package documentation with code examples
  • Security best practices section
  • Common use cases with practical examples
  • Installation and requirements sections
  • Testing and contributing guidelines
  • Related projects and support links
• Added llm.txt (727 lines), providing complete SDK context for AI-powered development tools, including:
  • Package index and API reference
  • Security principles and best practices
  • Code examples for all major features
  • Migration guides and common pitfalls
  • Performance considerations

Testing

Linter:

• All golangci-lint v2.6.1 checks pass
• No new linter warnings introduced

Unit Tests:

• All existing tests pass unchanged
• Test behaviour remains identical (logic fixes are semantic clarifications)

Manual Testing:

• Verified GitHub Actions workflow syntax is valid
• Confirmed golangci-lint runs successfully with the new version

Breaking Changes

✅ No breaking changes

All changes are internal:

• Tooling updates don't affect library consumers
• Logic fixes correct the implementation to match the original intent
• Documentation improvements are additive
• Error handling improvements are in the test code only

Dependencies

• Updated CI dependencies:
  • golangci/golangci-lint-action: v6.5.2 → v9.0.0
  • golangci-lint: v1.64.8 → v2.6.1
  • gotestsum: 1.12.1 → 1.13.0
• Updated Nix flake.lock (nixpkgs)
• No Go module dependencies changed

Checklist

• Code follows Go idioms and project conventions
• All tests pass (go test ./...)
• Code formatted with gofmt
• Linter passes without errors (golangci-lint v2.6.1)
• Documentation updated (README.md, llm.txt added)
• No breaking changes introduced
• Error handling improved in test code

Related Issues

This is a routine maintenance update with no associated issues.

Notable Changes Details

Logic Fixes Explanation

The logical operator changes in tar and zip extract functions are technically equivalent but more explicit:

Before:

if !(fi.IsDir() && hdr.Typeflag == tar.TypeDir) {
    // Remove existing file
}

After:

if !fi.IsDir() || hdr.Typeflag != tar.TypeDir {
    // Remove existing file  
}

By De Morgan's law: !(A && B) ≡ (!A || !B). The new form is clearer about the intent: remove the existing file if EITHER it's not a directory OR the new entry is not a directory.

Golangci-lint Version Jump

The jump from v1.x to v2.x of golangci-lint includes:

• Improved Go 1.24 support
• Updated linter rules and defaults
• Better performance and accuracy

Removal of .golangci.yml indicates using sensible defaults rather than extensive customisation.