docs: add canonical envvars.md reference and fix OPENSEARCH_GO_ROUTER default (#884)

* fix: add canonical envvars.md reference and fix OPENSEARCH_GO_ROUTER default

Add guides/envvars.md as the single authoritative reference for every
OPENSEARCH_GO_* runtime environment variable -- accepted values, defaults,
meanings, and the exhaustive OPENSEARCH_GO_ERROR_MASK token list.

Consolidate scattered env var documentation by pointing existing references
at the new guide instead of re-describing values inline:
- USER_GUIDE.md: replace partial env var summary table with a link
- opensearchapi/README.md: link error-mask env override to envvars.md tokens
- guides/error_handling.md: link to envvars.md for the canonical token list
- guides/routing.md: cross-link configuration reference to envvars.md

Fix a documentation bug where routing.md listed OPENSEARCH_GO_ROUTER's
default as false; the correct default is true (router auto-constructed
when unset, matching the actual behaviour and USER_GUIDE.md).

Signed-off-by: molloyzak13 <molloyzak13@users.noreply.github.com>

* chore: add CHANGELOG entry for envvars.md documentation

Closes #883

Signed-off-by: molloyzak13 <molloyzak13@users.noreply.github.com>

* docs: fix envvars.md defaults, add build/test section, fix broken link

- Correct OPENSEARCH_GO_STANDBY_ROTATION_INTERVAL default (0=use
  DiscoverNodesInterval, not 30s)
- Correct shard-cost 'unknown' example (32.0, not 16.0)
- Fix OPENSEARCH_GO_DEBUG See-also anchor (#debugging)
- Clarify overload thresholds use >= comparison; drop incorrect
  '100/1.0 disables detection' claims
- Add Build/test/development section per issue #883
- Note EnableDebugLogger equivalent for OPENSEARCH_GO_DEBUG

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

* feat(opensearchtransport): add OPENSEARCH_GO_POLICY_DUMP router-tree dump

Dumps the router policy tree (labeled node paths) via the debug logger at
client init when OPENSEARCH_GO_POLICY_DUMP=true and OPENSEARCH_GO_DEBUG=true.
The render walks the structural tree directly rather than reusing the
pointer-keyed buildPolicyPaths map, which collapsed router wrappers that share
a single inner policy instance (the default router has 12 router nodes but only
5 distinct inner policies); each node is now rendered in full and labeled with
its pool or role.

Document in guides/envvars.md: godoc links on the policy-type column, a
dedicated path-matcher section, the reference default-router DOM, and a
Quick-reference table promoted to a top-of-document TOC with the rationale for
the env-var surface.

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

---------

Signed-off-by: molloyzak13 <molloyzak13@users.noreply.github.com>
Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>
Co-authored-by: molloyzak13 <molloyzak13@users.noreply.github.com>
Co-authored-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: molloyzak13

CHANGELOG.md

@@ -6,6 +6,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Added
 
+- Add `OPENSEARCH_GO_POLICY_DUMP` environment variable: when set with `OPENSEARCH_GO_DEBUG=true`, dumps the router's policy tree (the dot-delimited node paths that `OPENSEARCH_GO_POLICY_*` matchers target, each labeled with its pool or role) to the debug logger at client initialization. The dump walks the structural tree so router wrappers that share an inner policy instance are each rendered in full. ([#883](https://github.com/opensearch-project/opensearch-go/issues/883))
 - Add a `build-samples` Makefile target and a CI job that compiles and vets every `_samples/*.go` program, so example breakage is caught (the `_samples` directory is excluded from `go build ./...` because Go ignores `_`-prefixed paths)
 - Group document operations under a `client.Doc` sub-client and point-in-time operations under `client.PIT` (`Create`/`Delete`/`GetAll`/`DeleteAll`); `client.Document` and `client.PointInTime` remain as field aliases. The indices sub-client's canonical field is `client.Index`, with `client.Indices` and `client.Indexes` as aliases. `cmd/osgen` gains `--emit-v4-compat` (default true) to emit backward-compatibility forwarders so top-level `client.Bulk`/`MGet`/`Update`, `client.Document.Source`, and `client.PointInTime.Get` keep working (`client.Index` is not forwarded -- it is the indices sub-client field; use `client.Doc.Index`), and `--emit-v4-deprecation` (default false) to mark those forwarders deprecated
 - Add `cmd/osgen` code generator for typed path builders and API consumer files from the OpenAPI spec
@@ -158,6 +159,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Add `Routing` and `Fields` to `MGetResp.Docs` to match the full OpenSearch `_mget` response format
 - Add `ForcedRefresh` field to `IndexResp`, `DocumentDeleteResp`, and `UpdateResp` for consistency with `DocumentCreateResp`
 - Add `Status` and `Primary` fields to `ResponseShardsFailure` for shard failure diagnostics
+- Add `guides/envvars.md` as the canonical reference for every `OPENSEARCH_GO_*` environment variable — accepted values, defaults, parsing rules, and the exhaustive `OPENSEARCH_GO_ERROR_MASK` token list. Fix `OPENSEARCH_GO_ROUTER` default in `routing.md` from incorrect `false` to correct `true`. ([#883](https://github.com/opensearch-project/opensearch-go/issues/883))
 
 ### Changed
 

USER_GUIDE.md

@@ -548,24 +548,7 @@ Set `OPENSEARCH_GO_DEBUG=true` to see policy paths and override actions. See [Re
 
 ## Environment Variables
 
-All `OPENSEARCH_GO_*` environment variables are evaluated once at client initialization. A complete reference is in [Request Routing: Configuration Reference](guides/routing.md#14-configuration-reference). Quick summary:
-
-| Variable                            | Default       | Description                                                                 |
-| ----------------------------------- | ------------- | --------------------------------------------------------------------------- |
-| `OPENSEARCH_GO_REQUEST_TIMEOUT`     | 0 (none)      | Per-attempt HTTP request timeout (duration or secs)                         |
-| `OPENSEARCH_GO_DEBUG`               | `false`       | Debug logging to stderr                                                     |
-| `OPENSEARCH_GO_ROUTER`              | (on)          | Auto-construct DefaultRouter when no Router is set; set `false`/`0` to disable |
-| `OPENSEARCH_GO_ROUTING_CONFIG`      | (all enabled) | Shard-exact routing (`-shard_exact`)                                        |
-| `OPENSEARCH_GO_SHARD_REQUESTS`      | `true`        | Adaptive `max_concurrent_shard_requests` bounds                             |
-| `OPENSEARCH_GO_SHARD_COST`          | (defaults)    | Shard cost multipliers for connection scoring                               |
-| `OPENSEARCH_GO_DISCOVERY_CONFIG`    | (all enabled) | Skip specific discovery calls                                               |
-| `OPENSEARCH_GO_FALLBACK`            | `true`        | Seed URL fallback when all pools exhausted                                  |
-| `OPENSEARCH_GO_NODE_STATS_INTERVAL` | auto (5s-30s) | Stats polling interval                                                      |
-| `OPENSEARCH_GO_POLICY_*`            | (all enabled) | Disable specific routing policies (10 variables)                            |
-| `OPENSEARCH_GO_ACTIVE_LIST_CAP`     | auto          | Max active connections per pool                                             |
-| `OPENSEARCH_GO_STANDBY_*`           | (see guide)   | Standby rotation and promotion tuning (3 variables)                         |
-| `OPENSEARCH_GO_OVERLOADED_*`        | (see guide)   | JVM heap and breaker thresholds (2 variables)                               |
-| `OPENSEARCH_GO_ERROR_MASK`          | (version-dep) | Mask partial-failure categories (`+`/`-` tokens; overrides `Config.Errors`) |
+All `OPENSEARCH_GO_*` environment variables are evaluated once at client initialization and are immutable after. The canonical reference for every variable — accepted values, defaults, meanings, and the tokens accepted by `OPENSEARCH_GO_ERROR_MASK` — is [guides/envvars.md](guides/envvars.md). The sections below link to the relevant categories in that guide.
 
 ## Guides by Topic