revert: remove duplicate of analysis

## Description

Tool versions were not pinned to the repository: this caused issues with upgrades.

## Changes

- Use `go tool` for `checkmake`, `gremlins`, `golangci-lint`, `godoc` and `govulncheck`.

### Design Decisions

## Checklist

- [x] Tests pass
- [x] Docs updated

Reviewed-on: #25
Co-authored-by: M.V. Hutz <git@maximhutz.me>
Co-committed-by: M.V. Hutz <git@maximhutz.me>

.gitea/workflows/ci.yml

@@ -32,9 +32,8 @@ jobs:
       - name: Check go mod tidy
         run: go mod tidy && git diff --exit-code go.mod go.sum
 
-      - uses: golangci/golangci-lint-action@v7
+      - name: Run linter
-        with:
+        run: make lint-go
-          version: latest
 
   lint-makefile:
     name: Makefile Lint
@@ -46,9 +45,6 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Install gremlins
-        run: go install github.com/checkmake/checkmake/cmd/checkmake@latest
-
       - name: Run mutation tests
         run: make lint-makefile
 
@@ -96,8 +92,5 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Install gremlins
-        run: go install github.com/go-gremlins/gremlins/cmd/gremlins@latest
-
       - name: Run mutation tests
         run: make test-mutation

Makefile

@@ -4,17 +4,13 @@ help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk -F ':.*## ' '{printf "  %-15s %s\n", $$1, $$2}'
 
 install: ## Install dev tools
-	go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+	go mod download
-	go install github.com/checkmake/checkmake/cmd/checkmake@latest
-	go install github.com/go-gremlins/gremlins/cmd/gremlins@latest
-	go install golang.org/x/tools/cmd/godoc@latest
-	go install golang.org/x/vuln/cmd/govulncheck@latest
 
 test-unit: ## Run unit tests with coverage
 	go test ./... -cover -v
 
 test-mutation: ## Run mutation tests with gremlins
-	gremlins unleash
+	go tool gremlins unleash
 
 FUZZ_TIME ?= 30
 
@@ -27,10 +23,10 @@ test-fuzz: ## Run all fuzz tests for 30s each
 test: test-unit test-mutation test-fuzz ## Run all tests
 
 lint-go: ## Lint Go code
-	golangci-lint run ./...
+	go tool golangci-lint run ./...
 
 lint-makefile: ## Lint the Makefile
-	checkmake Makefile
+	go tool checkmake Makefile
 
 lint-markdown: ## Lint Markdown files
 	docker run --rm -v $(CURDIR):/workdir davidanson/markdownlint-cli2 "**/*.md"
@@ -39,7 +35,7 @@ lint: lint-go lint-makefile lint-markdown ## Lint all code
 
 docs: ## Serve godoc locally
 	@echo ">>> Visit: http://localhost:6060/pkg/$$(go list -m)"
-	godoc -http=:6060
+	go tool godoc -http=:6060
 
 clean: ## Clean build and test caches
 	go clean -cache -testcache

docs/adr/000_template.md

@@ -0,0 +1,15 @@
+# Title
+
+**Status**: <!-- Proposed, accepted, rejected, etc... -->
+
+## Context
+
+<!-- What is the issue that we're seeing that is motivating this decision or change? -->
+
+## Decision
+
+<!-- What is the change that we're proposing and/or doing? -->
+
+## Consequences
+
+<!-- What becomes easier or more difficult to do because of this change? -->

docs/adr/001_design_principles.md

@@ -0,0 +1,44 @@
+# Adopt Congruent and Familiar Design For `go-cuckoo`
+
+**Status**: Proposed
+
+## Context
+
+I built `go-cuckoo`'s API interface without design intent.
+Up until now, I paid more attention implementing the underlying functionality of the cuckoo hashing.
+With the fundamentals of the algorithm built, I should revisit the interface.
+
+The goal of this project was to create an implementation of cuckoo hashing, while adhering to Go's idioms, and being as usable as possible.
+While the implementation does work, it lacks direction.
+
+## Decision
+
+To resolve this, I'm enforcing two new principles onto the contract of `go-cuckoo`:
+
+- **Congruency**:
+  A `go-cuckoo` table should have the same core functionality as Go's built-in map.
+
+- **Familiarity**:
+  A `go-cuckoo` table should behave similarly to Go's standard map, so users will intuitively know how to use it.
+  In effect, its users will carry less cognitive load.
+
+These principles should _guide_ the public interface of `go-cuckoo`.
+Neither should be treated absolutely, though.
+The behavior of `go-cuckoo` is distinct from `map`.
+Do not equate them.
+
+## Consequences
+
+1. The repository should support both design principles.
+   - [ ] Update the `README.md` and `doc.go` to reflect these principles.
+   - [ ] Update the contributing guide and pull request template to require these principles are met.
+2. The repository should contain a living document, describing the interface differences between `go-cuckoo` and `map`.
+   I should prioritize limiting any incongruencies.
+   - [ ] Produce the first draft to uncover any current incongruencies.
+   - [ ] Link the document to the `README.md`.
+3. Analyze the familiarity of `go-cuckoo`'s current interface.
+   Unlike the analysis of congruency, this should be a one time document.
+   Familiarity is implicit to users, and does not need to be referenced.
+   But, any rationale should be documented in commit messages, or future ADRs.
+   - [ ] Produce the analysis document.
+   - [ ] Resolve any issues found.

go.mod

@@ -4,7 +4,225 @@ go 1.25.6
 
 require github.com/stretchr/testify v1.11.1
 
-require github.com/kr/pretty v0.3.1 // indirect
+require (
+	4d63.com/gocheckcompilerdirectives v1.3.0 // indirect
+	4d63.com/gochecknoglobals v0.2.2 // indirect
+	charm.land/lipgloss/v2 v2.0.3 // indirect
+	codeberg.org/chavacava/garif v0.2.0 // indirect
+	codeberg.org/polyfloyd/go-errorlint v1.9.0 // indirect
+	dev.gaijin.team/go/exhaustruct/v4 v4.0.0 // indirect
+	dev.gaijin.team/go/golib v0.6.0 // indirect
+	github.com/4meepo/tagalign v1.4.3 // indirect
+	github.com/Abirdcfly/dupword v0.1.7 // indirect
+	github.com/AdminBenni/iota-mixing v1.0.0 // indirect
+	github.com/AlwxSin/noinlineerr v1.0.5 // indirect
+	github.com/Antonboom/errname v1.1.1 // indirect
+	github.com/Antonboom/nilnil v1.1.1 // indirect
+	github.com/Antonboom/testifylint v1.6.4 // indirect
+	github.com/BurntSushi/toml v1.6.0 // indirect
+	github.com/ClickHouse/clickhouse-go-linter v1.2.0 // indirect
+	github.com/Djarvur/go-err113 v0.1.1 // indirect
+	github.com/MakeNowJust/heredoc v1.0.0 // indirect
+	github.com/Masterminds/semver/v3 v3.5.0 // indirect
+	github.com/MirrexOne/unqueryvet v1.5.4 // indirect
+	github.com/OpenPeeDeeP/depguard/v2 v2.2.1 // indirect
+	github.com/alecthomas/chroma/v2 v2.24.1 // indirect
+	github.com/alecthomas/go-check-sumtype v0.3.1 // indirect
+	github.com/alexkohler/nakedret/v2 v2.0.6 // indirect
+	github.com/alexkohler/prealloc v1.1.0 // indirect
+	github.com/alfatraining/structtag v1.0.0 // indirect
+	github.com/alingse/asasalint v0.0.11 // indirect
+	github.com/alingse/nilnesserr v0.2.0 // indirect
+	github.com/ashanbrown/forbidigo/v2 v2.3.1 // indirect
+	github.com/ashanbrown/makezero/v2 v2.2.1 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/bkielbasa/cyclop v1.2.3 // indirect
+	github.com/blizzy78/varnamelen v0.8.0 // indirect
+	github.com/bluekeyes/go-gitdiff v0.8.1 // indirect
+	github.com/bombsimon/wsl/v4 v4.7.0 // indirect
+	github.com/bombsimon/wsl/v5 v5.8.0 // indirect
+	github.com/breml/bidichk v0.3.3 // indirect
+	github.com/breml/errchkjson v0.4.1 // indirect
+	github.com/butuzov/ireturn v0.4.1 // indirect
+	github.com/butuzov/mirror v1.3.0 // indirect
+	github.com/catenacyber/perfsprint v0.10.1 // indirect
+	github.com/ccojocar/zxcvbn-go v1.0.4 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/charithe/durationcheck v0.0.11 // indirect
+	github.com/charmbracelet/colorprofile v0.4.3 // indirect
+	github.com/charmbracelet/ultraviolet v0.0.0-20251205161215-1948445e3318 // indirect
+	github.com/charmbracelet/x/ansi v0.11.7 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/charmbracelet/x/termios v0.1.1 // indirect
+	github.com/charmbracelet/x/windows v0.2.2 // indirect
+	github.com/checkmake/checkmake v0.3.2 // indirect
+	github.com/ckaznocha/intrange v0.3.1 // indirect
+	github.com/clipperhouse/displaywidth v0.11.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
+	github.com/curioswitch/go-reassign v0.3.0 // indirect
+	github.com/daixiang0/gci v0.13.7 // indirect
+	github.com/dave/dst v0.27.3 // indirect
+	github.com/denis-tingaikin/go-header v0.5.0 // indirect
+	github.com/dlclark/regexp2 v1.12.0 // indirect
+	github.com/ettle/strcase v0.2.0 // indirect
+	github.com/fatih/color v1.19.0 // indirect
+	github.com/fatih/structtag v1.2.0 // indirect
+	github.com/firefart/nonamedreturns v1.0.6 // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/fzipp/gocyclo v0.6.0 // indirect
+	github.com/ghostiam/protogetter v0.3.20 // indirect
+	github.com/go-critic/go-critic v0.14.3 // indirect
+	github.com/go-gremlins/gremlins v0.6.0 // indirect
+	github.com/go-ini/ini v1.67.0 // indirect
+	github.com/go-toolsmith/astcast v1.1.0 // indirect
+	github.com/go-toolsmith/astcopy v1.1.0 // indirect
+	github.com/go-toolsmith/astequal v1.2.0 // indirect
+	github.com/go-toolsmith/astfmt v1.1.0 // indirect
+	github.com/go-toolsmith/astp v1.1.0 // indirect
+	github.com/go-toolsmith/strparse v1.1.0 // indirect
+	github.com/go-toolsmith/typep v1.1.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/go-xmlfmt/xmlfmt v1.1.3 // indirect
+	github.com/gobwas/glob v0.2.3 // indirect
+	github.com/godoc-lint/godoc-lint v0.11.2 // indirect
+	github.com/gofrs/flock v0.13.0 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/golangci/asciicheck v0.5.0 // indirect
+	github.com/golangci/dupl v0.0.0-20260401084720-c99c5cf5c202 // indirect
+	github.com/golangci/go-printf-func-name v0.1.1 // indirect
+	github.com/golangci/gofmt v0.0.0-20250106114630-d62b90e6713d // indirect
+	github.com/golangci/golangci-lint/v2 v2.12.2 // indirect
+	github.com/golangci/golines v0.15.0 // indirect
+	github.com/golangci/misspell v0.8.0 // indirect
+	github.com/golangci/plugin-module-register v0.1.2 // indirect
+	github.com/golangci/revgrep v0.8.0 // indirect
+	github.com/golangci/rowserrcheck v0.0.0-20260419091836-c5f79b8a11ba // indirect
+	github.com/golangci/swaggoswag v0.0.0-20250504205917-77f2aca3143e // indirect
+	github.com/golangci/unconvert v0.0.0-20250410112200-a129a6e6413e // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/gordonklaus/ineffassign v0.2.0 // indirect
+	github.com/gostaticanalysis/analysisutil v0.7.1 // indirect
+	github.com/gostaticanalysis/comment v1.5.0 // indirect
+	github.com/gostaticanalysis/forcetypeassert v0.2.0 // indirect
+	github.com/gostaticanalysis/nilerr v0.1.2 // indirect
+	github.com/hako/durafmt v0.0.0-20210608085754-5c1018a4e16b // indirect
+	github.com/hashicorp/go-immutable-radix/v2 v2.1.0 // indirect
+	github.com/hashicorp/go-version v1.9.0 // indirect
+	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
+	github.com/hexops/gotextdiff v1.0.3 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jgautheron/goconst v1.10.0 // indirect
+	github.com/jjti/go-spancheck v0.6.5 // indirect
+	github.com/julz/importas v0.2.0 // indirect
+	github.com/karamaru-alpha/copyloopvar v1.2.2 // indirect
+	github.com/kisielk/errcheck v1.10.0 // indirect
+	github.com/kkHAIKE/contextcheck v1.1.6 // indirect
+	github.com/kulti/thelper v0.7.1 // indirect
+	github.com/kunwardeep/paralleltest v1.0.15 // indirect
+	github.com/lasiar/canonicalheader v1.1.2 // indirect
+	github.com/ldez/exptostd v0.4.5 // indirect
+	github.com/ldez/gomoddirectives v0.8.0 // indirect
+	github.com/ldez/grignotin v0.10.1 // indirect
+	github.com/ldez/structtags v0.6.1 // indirect
+	github.com/ldez/tagliatelle v0.7.2 // indirect
+	github.com/ldez/usetesting v0.5.0 // indirect
+	github.com/leonklingele/grouper v1.1.2 // indirect
+	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
+	github.com/macabu/inamedparam v0.2.0 // indirect
+	github.com/manuelarte/embeddedstructfieldcheck v0.4.0 // indirect
+	github.com/manuelarte/funcorder v0.6.0 // indirect
+	github.com/maratori/testableexamples v1.0.1 // indirect
+	github.com/maratori/testpackage v1.1.2 // indirect
+	github.com/matoous/godox v1.1.0 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-runewidth v0.0.23 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect
+	github.com/mgechev/revive v1.15.0 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
+	github.com/moricho/tparallel v0.3.2 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/nakabonne/nestif v0.3.1 // indirect
+	github.com/nishanths/exhaustive v0.12.0 // indirect
+	github.com/nishanths/predeclared v0.2.2 // indirect
+	github.com/nunnatsa/ginkgolinter v0.23.0 // indirect
+	github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6 // indirect
+	github.com/olekukonko/errors v1.1.0 // indirect
+	github.com/olekukonko/ll v0.1.3 // indirect
+	github.com/olekukonko/tablewriter v1.1.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.3.1 // indirect
+	github.com/prometheus/client_golang v1.12.1 // indirect
+	github.com/prometheus/client_model v0.2.0 // indirect
+	github.com/prometheus/common v0.32.1 // indirect
+	github.com/prometheus/procfs v0.7.3 // indirect
+	github.com/quasilyte/go-ruleguard v0.4.5 // indirect
+	github.com/quasilyte/go-ruleguard/dsl v0.3.23 // indirect
+	github.com/quasilyte/gogrep v0.5.0 // indirect
+	github.com/quasilyte/regex/syntax v0.0.0-20210819130434-b3f0c404a727 // indirect
+	github.com/quasilyte/stdinfo v0.0.0-20220114132959-f7386bf02567 // indirect
+	github.com/raeperd/recvcheck v0.2.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	github.com/ryancurrah/gomodguard v1.4.1 // indirect
+	github.com/ryancurrah/gomodguard/v2 v2.1.3 // indirect
+	github.com/ryanrolds/sqlclosecheck v0.6.0 // indirect
+	github.com/sagikazarmark/locafero v0.12.0 // indirect
+	github.com/sanposhiho/wastedassign/v2 v2.1.0 // indirect
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
+	github.com/sashamelentyev/interfacebloat v1.1.0 // indirect
+	github.com/sashamelentyev/usestdlibvars v1.29.0 // indirect
+	github.com/securego/gosec/v2 v2.26.1 // indirect
+	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/sivchari/containedctx v1.0.3 // indirect
+	github.com/sonatard/noctx v0.5.1 // indirect
+	github.com/sourcegraph/go-diff v0.8.0 // indirect
+	github.com/spf13/afero v1.15.0 // indirect
+	github.com/spf13/cast v1.10.0 // indirect
+	github.com/spf13/cobra v1.10.2 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
+	github.com/spf13/viper v1.21.0 // indirect
+	github.com/ssgreg/nlreturn/v2 v2.2.1 // indirect
+	github.com/stbenjam/no-sprintf-host-port v0.3.1 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/subosito/gotenv v1.6.0 // indirect
+	github.com/tetafro/godot v1.5.6 // indirect
+	github.com/timakin/bodyclose v0.0.0-20260129054331-73d1f95b84b4 // indirect
+	github.com/timonwong/loggercheck v0.11.0 // indirect
+	github.com/tomarrell/wrapcheck/v2 v2.12.0 // indirect
+	github.com/tommy-muehle/go-mnd/v2 v2.5.1 // indirect
+	github.com/ultraware/funlen v0.2.0 // indirect
+	github.com/ultraware/whitespace v0.2.0 // indirect
+	github.com/uudashr/gocognit v1.2.1 // indirect
+	github.com/uudashr/iface v1.4.2 // indirect
+	github.com/xen0n/gosmopolitan v1.3.0 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	github.com/yagipy/maintidx v1.0.0 // indirect
+	github.com/yeya24/promlinter v0.3.0 // indirect
+	github.com/ykadowak/zerologlint v0.1.5 // indirect
+	github.com/yuin/goldmark v1.7.13 // indirect
+	gitlab.com/bosi/decorder v0.4.2 // indirect
+	go-simpler.org/musttag v0.14.0 // indirect
+	go-simpler.org/sloglint v0.12.0 // indirect
+	go.augendre.info/arangolint v0.4.0 // indirect
+	go.augendre.info/fatcontext v0.9.0 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	go.uber.org/zap v1.27.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/exp/typeparams v0.0.0-20260209203927-2842357ff358 // indirect
+	golang.org/x/mod v0.35.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/telemetry v0.0.0-20260421165255-392afab6f40e // indirect
+	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/tools v0.44.0 // indirect
+	golang.org/x/tools/cmd/godoc v0.1.0-deprecated // indirect
+	golang.org/x/tools/godoc v0.1.0-deprecated // indirect
+	golang.org/x/vuln v1.3.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+	honnef.co/go/tools v0.7.0 // indirect
+	mvdan.cc/gofumpt v0.9.2 // indirect
+	mvdan.cc/unparam v0.0.0-20251027182757-5beb8c8f8f15 // indirect
+)
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
@@ -12,3 +230,11 @@ require (
 	github.com/trailofbits/go-fuzz-utils v0.0.0-20260318143407-0907cafe7589
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
+
+tool (
+	github.com/checkmake/checkmake/cmd/checkmake
+	github.com/go-gremlins/gremlins/cmd/gremlins
+	github.com/golangci/golangci-lint/v2/cmd/golangci-lint
+	golang.org/x/tools/cmd/godoc
+	golang.org/x/vuln/cmd/govulncheck
+)

wip/INTERFACE_ANALYSIS.md

@@ -1,5 +1,14 @@
 # Designing an Idiomatic API Interface
 
+- [Designing an Idiomatic API Interface](#designing-an-idiomatic-api-interface)
+  - [Current State](#current-state)
+    - [Interface of the Built-in Map](#interface-of-the-built-in-map)
+    - [Interface of `go-cuckoo`](#interface-of-go-cuckoo)
+    - [Determining Congruency](#determining-congruency)
+    - [Determining Familiarity](#determining-familiarity)
+  - [Target State](#target-state)
+    - [Solving Congruency](#solving-congruency)
+
 We (the maintainers) built `go-cuckoo`'s API interface without design intent.
 Up until now, we paid more attention implementing the underlying functionality of the cuckoo hashing.
 
@@ -15,7 +24,7 @@ It should align closer to the following principles:
 
 ## Current State
 
-### Interface of the built-in Map
+### Interface of the Built-in Map
 
 Listed below is every interface provided by Go to the built-in map object.
 Also included, are the functions from the package `maps` in the standard library.
@@ -23,7 +32,7 @@ Also included, are the functions from the package `maps` in the standard library
 <details>
 <summary>Interfaces</summary>
 
-| #   | built-in Interface                 | Description                                                                                                                                           |
+| #   | Built-in Interface                 | Description                                                                                                                                           |
 | --- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1   | `m := make(map[K]V)`               | Returns an empty map using the built-in `make()` function.                                                                                            |
 | 2   | `m := make(map[K]V, hint)`         | Returns an empty map using `make()`, with a capacity 'hint'. This hint is how many items the map expects to hold, _not_ a measure of how large it is. |
@@ -56,7 +65,7 @@ On the other hand, here is the current contract for `go-cuckoo`.
 <details>
 <summary>Interfaces</summary>
 
-| #   | built-in Interface                                 | Description                                                                                                                  |
+| #   | `go-cuckoo` Interface                              | Description                                                                                                                  |
 | --- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | 1   | `m := New(opts...)`                                | Creates a table using the default hash and equal function. The options configure its behavior. Confined to comparable keys.  |
 | 2   | `m := NewBy(keyFunc, opts...)`                     | Like #1, but allows any key type. A `keyFunc` is used to derive a comparable key.                                            |
@@ -307,6 +316,98 @@ There is no analog.
 
 </details>
 
+### Determining Familiarity
+
+We can categorize all existing table functionality by each interface's familiarity:
+
+- ✅ Idiomatic: is clear, intuitive, and easily understood.
+- ❌ Non-idiomatic: is misleading; addressed in [Target State](#solving-congruency).
+
+<details>
+<summary>✅ <code>m := New(opts...)</code></summary>
+
+Criteria:
+
+Noun/adjective form — Go constructors use NewX where X is a noun or adjective, not a verb or past participle (NewReaderSize, not NewSized)
+Names what the user provides — the suffix should hint at the distinguishing parameter (NewBufferString tells you it takes a string)
+Progression is readable — the three names together should imply simple → intermediate → advanced
+Not misleadingly generic — NewWith or NewConfig could mean anything
+
+</details>
+
+<details>
+<summary><code>m := NewBy(keyFunc, opts...)</code></summary>
+
+- Use `NewKeyed()`.
+
+</details>
+
+<details>
+<summary><code>m := NewCustom(hashA, hashB, equalFunc, opts...)</code></summary>
+
+- Use `NewHashed()`.
+
+</details>
+
+<details>
+<summary>❌ <code>seq := m.Entries()</code></summary>
+
+- Call it `All()`.
+
+</details>
+
+<details>
+<summary><code>v := m.Find(k)</code></summary>
+
+- Call it `m.Lookup()`. The name `m.Find` implies a search algorithm.
+
+</details>
+
+<details>
+<summary><code>v, ok := m.Get(k)</code></summary>
+
+</details>
+
+<details>
+<summary><code>ok := m.Has(k)</code></summary>
+
+</details>
+
+<details>
+<summary>❌ <code>err := m.Put(k, v)</code></summary>
+
+- Call it `Set()`.
+- No built-in library consensus, but 3rd party packages prefer `Set()`.
+
+</details>
+
+<details>
+<summary>❌ <code>n := m.Size()</code></summary>
+
+- Call it `Len()`.
+- Size is a Java idiom.
+
+</details>
+
+<details>
+<summary>✅ <code>str := m.String()</code></summary>
+
+</details>
+
+<details>
+<summary>❌ <code>cap := m.TotalCapacity()</code></summary>
+
+- Remove. This is an implementation detail.
+
+</details>
+
+<details>
+<summary>❌ <code>ok := m.Drop(k)</code></summary>
+
+- Call it `Delete()`.
+
+</details>
+
 ## Target State
 
 ### Solving Congruency