feat(sieve): add the remaining collection helpers and docs mentions

- Add TryMap, Filter, Reduce, KeyBy, GroupBy, Uniq, UniqBy, Partition
  and Find, plus the Set type built with SetOf (Has, Add, Slice).
- Add unit tests at 100% statement coverage and a runnable example for
  every function and Set method.
- Complete the module README: contracts, use cases, Pluck rationale,
  standard-library pointers and the full API reference.
- docs/architecture/introduction.md: add a Utilities row for sieve.
- docs/setup/coming-from-wintercms.md: map Laravel collection methods
  to sieve and narrow the not-provided row to the fluent collection
  object.

modules/sieve/example_test.go

@@ -2,13 +2,22 @@ package sieve_test
 
 import (
 	"fmt"
+	"slices"
+	"strconv"
 
 	"git.golem15.com/golem15/summercms/modules/sieve"
 )
 
 type post struct {
-	ID    int
-	Title string
+	ID     int
+	Author string
+	Title  string
+}
+
+var posts = []post{
+	{ID: 1, Author: "ana", Title: "Hello"},
+	{ID: 2, Author: "bob", Title: "Summer"},
+	{ID: 3, Author: "ana", Title: "Goodbye"},
 }
 
 func ExampleMap() {
@@ -22,3 +31,96 @@ func ExampleMap() {
 	fmt.Println(titles)
 	// Output: [Hello Summer Goodbye]
 }
+
+func ExampleTryMap() {
+	nums, err := sieve.TryMap([]string{"1", "2", "3"}, strconv.Atoi)
+	fmt.Println(nums, err)
+
+	nums, err = sieve.TryMap([]string{"1", "x", "3"}, strconv.Atoi)
+	fmt.Println(nums, err)
+	// Output:
+	// [1 2 3] <nil>
+	// [] strconv.Atoi: parsing "x": invalid syntax
+}
+
+func ExampleFilter() {
+	byAna := sieve.Filter(posts, func(p post) bool { return p.Author == "ana" })
+	fmt.Println(len(byAna), byAna[0].Title, byAna[1].Title)
+	// Output: 2 Hello Goodbye
+}
+
+func ExampleReduce() {
+	total := sieve.Reduce([]int{1, 2, 3, 4}, 0, func(sum, v int) int { return sum + v })
+	fmt.Println(total)
+	// Output: 10
+}
+
+func ExampleKeyBy() {
+	byID := sieve.KeyBy(posts, func(p post) int { return p.ID })
+	fmt.Println(byID[2].Title, len(byID))
+	// Output: Summer 3
+}
+
+func ExampleGroupBy() {
+	byAuthor := sieve.GroupBy(posts, func(p post) string { return p.Author })
+	titles := make(map[string][]string, len(byAuthor))
+	for author, group := range byAuthor {
+		titles[author] = sieve.Map(group, func(p post) string { return p.Title })
+	}
+	fmt.Println(titles)
+	// Output: map[ana:[Hello Goodbye] bob:[Summer]]
+}
+
+func ExampleUniq() {
+	fmt.Println(sieve.Uniq([]int{3, 1, 3, 2, 1}))
+	// Output: [3 1 2]
+}
+
+func ExampleUniqBy() {
+	firstPerAuthor := sieve.UniqBy(posts, func(p post) string { return p.Author })
+	fmt.Println(sieve.Map(firstPerAuthor, func(p post) string { return p.Title }))
+	// Output: [Hello Summer]
+}
+
+func ExamplePartition() {
+	even, odd := sieve.Partition([]int{1, 2, 3, 4, 5}, func(v int) bool { return v%2 == 0 })
+	fmt.Println(even, odd)
+	// Output: [2 4] [1 3 5]
+}
+
+func ExampleFind() {
+	p, ok := sieve.Find(posts, func(p post) bool { return p.Author == "bob" })
+	fmt.Println(p.Title, ok)
+
+	_, ok = sieve.Find(posts, func(p post) bool { return p.Author == "acme" })
+	fmt.Println(ok)
+	// Output:
+	// Summer true
+	// false
+}
+
+func ExampleSetOf() {
+	tags := sieve.SetOf("blog", "news", "blog")
+	fmt.Println(len(tags))
+	// Output: 2
+}
+
+func ExampleSet_Has() {
+	tags := sieve.SetOf("blog", "news")
+	fmt.Println(tags.Has("blog"), tags.Has("acme"))
+	// Output: true false
+}
+
+func ExampleSet_Add() {
+	tags := sieve.SetOf[string]()
+	tags.Add("blog", "news", "blog")
+	fmt.Println(len(tags), tags.Has("news"))
+	// Output: 2 true
+}
+
+func ExampleSet_Slice() {
+	ids := sieve.SetOf(3, 1, 2, 3).Slice()
+	slices.Sort(ids)
+	fmt.Println(ids)
+	// Output: [1 2 3]
+}