fix: sync docs with codebase — startup/shutdown sequences, API names, missing package

- architecture.md: fix startup sequence order (handlers register before
  servers start, not after), expand shutdown sequence to match actual
  code (9 steps including admin server, graceful stop, force stop),
  correct options API from Set/Get to AddToOptions/FromContext, add
  admin port to deployment topology diagram
- Packages.md: add missing options package entry
- integrations.md: fix Sentry env var RELEASE → RELEASE_NAME
- production.md, signals.md: add admin server shutdown step
- Index.md: add link to full interceptor chain from simplified diagram

Author: ankurs

Index.md

@@ -117,6 +117,8 @@ Run `buf generate` — it creates typed Go interfaces from your proto definition
                     │                                         │
                     │  /metrics  /healthcheck  /debug/pprof   │
                     └─────────────────────────────────────────┘
+
+See the [full interceptor chain](/architecture#server-interceptor-chain) for all 10 interceptors including timeout, rate limiting, debug logging, and New Relic.
 ```
 
 ## Packages

Packages.md

@@ -55,6 +55,11 @@ hystrixprometheus provides a Prometheus metrics collector for Hystrix (https://g
 
 Documentation can be found at [hystrixprometheus-docs]
 
+## [Options]
+options is a request-scoped key-value store that propagates metadata through `context.Context` using RWMutex+map. Used by interceptors to pass metadata between layers. Only string keys are supported.
+
+Documentation can be found at [options-docs]
+
 ## [grpcpool]
 grpcpool is a pool of grpc.ClientConns that can be used to make requests to a grpc server. It implements grpc.ClientConnInterface to enable it to be used directly with generated proto stubs.
 
@@ -93,4 +98,6 @@ Documentation can be found at [data-builder-docs]
 [workers-docs]: https://pkg.go.dev/github.com/go-coldbrew/workers
 [Data Builder]: https://github.com/go-coldbrew/data-builder/tree/main#readme
 [data-builder-docs]: https://pkg.go.dev/github.com/go-coldbrew/data-builder
+[Options]: https://github.com/go-coldbrew/options/tree/main#readme
+[options-docs]: https://pkg.go.dev/github.com/go-coldbrew/options
 [envconfig]: https://github.com/kelseyhightower/envconfig

architecture.md

@@ -275,8 +275,8 @@ ColdBrew uses `context.Context` to propagate metadata through every layer:
   context.Context
        │
        ├── options (key-value metadata)
-       │     Set: options.Set(ctx, key, value)
-       │     Get: options.Get(ctx, key)
+       │     Set: options.AddToOptions(ctx, key, value)
+       │     Get: options.FromContext(ctx).Get(key)
        │
        ├── log fields (per-request structured logging)
        │     Add: log.AddToContext(ctx, key, value)
@@ -299,7 +299,7 @@ Every interceptor reads from and writes to the context. By the time the request
 
 ## Deployment Topology
 
-A typical ColdBrew service exposes two ports:
+A typical ColdBrew service exposes two ports (optionally three with `ADMIN_PORT`):
 
 ```
   ┌─────────────────────────────────────────┐
@@ -314,10 +314,18 @@ A typical ColdBrew service exposes two ports:
   │   ├── /api/...     (REST gateway)       │
   │   ├── /healthcheck (liveness probe)     │
   │   ├── /readycheck  (readiness probe)    │
+  │   ├── /metrics     (Prometheus)*        │
+  │   ├── /swagger/    (OpenAPI UI)*        │
+  │   └── /debug/pprof/ (profiling)*        │
+  │                                         │
+  │   ADMIN_PORT (optional, e.g. 9092)      │
   │   ├── /metrics     (Prometheus)         │
   │   ├── /swagger/    (OpenAPI UI)         │
   │   └── /debug/pprof/ (profiling)         │
   └─────────────────────────────────────────┘
+
+  * When ADMIN_PORT is set, these endpoints move
+    to the admin port and are removed from 9091.
 ```
 
 ### Kubernetes Integration
@@ -365,19 +373,25 @@ func (s *svc) Echo(ctx context.Context, req *proto.EchoRequest) (*proto.EchoResp
 
 ### Startup Sequence
 
-1. Configuration loaded from environment variables
-2. Interceptor chain assembled (init-only, not thread-safe)
-3. gRPC server starts on port 9090
-4. HTTP gateway starts on port 9091
-5. Service registers handlers (`InitGRPC`, `InitHTTP`)
-6. Service marks itself as ready (`SetReady()`)
-7. Server blocks until shutdown signal
+1. Configuration loaded from environment variables (`core.New(cfg)`)
+2. Interceptor chain assembled during `init()` (not thread-safe)
+3. gRPC server created, service registers handlers (`InitGRPC`)
+4. Unix socket created for gateway (if `DISABLE_UNIX_GATEWAY=false`)
+5. HTTP server created, service registers handlers (`InitHTTP`)
+6. gRPC and HTTP servers start listening concurrently
+7. Admin server starts (if `ADMIN_PORT` is set)
+8. Server blocks until shutdown signal
 
 ### Shutdown Sequence
 
 1. SIGTERM/SIGINT received
-2. Service marked as not ready (`/readycheck` returns unhealthy)
-3. Kubernetes stops routing new traffic
-4. In-flight requests allowed to complete
-5. `Stop()` called on the service (your cleanup logic)
-6. Server exits
+2. `FailCheck(true)` on `CBGracefulStopper` services — `/readycheck` starts failing
+3. Wait `GRPC_GRACEFUL_DURATION_IN_SECONDS` (default 7s) for load balancer to drain
+4. Shutdown admin server (if configured)
+5. Shutdown HTTP server (stop accepting new requests)
+6. `GracefulStop()` gRPC server (finish in-flight RPCs, reject new ones)
+7. Force-stop gRPC server if graceful shutdown didn't complete in time
+8. `Stop()` called on `CBStopper` services (your cleanup logic)
+9. Exit
+
+See [Signal Handling and Graceful Shutdown](/howto/signals) for configuration and tuning details.

howto/production.md

@@ -179,11 +179,12 @@ ColdBrew's shutdown sequence (bounded by `SHUTDOWN_DURATION_IN_SECONDS`, default
 1. Receive SIGTERM from Kubernetes
 2. `FailCheck(true)` on `CBGracefulStopper` services — `/readycheck` starts failing
 3. Wait `GRPC_GRACEFUL_DURATION_IN_SECONDS` (default: 7s, included in shutdown timeout) for the load balancer to drain
-4. Shutdown HTTP server (stop accepting new requests)
-5. `GracefulStop()` gRPC server (finish in-flight RPCs, reject new ones)
-6. Force-stop gRPC server if graceful shutdown didn't complete in time
-7. Call `Stop()` on `CBStopper` services — close database pools, flush metrics, drain message producers
-8. Exit
+4. Shutdown admin server if configured (`ADMIN_PORT`)
+5. Shutdown HTTP server (stop accepting new requests)
+6. `GracefulStop()` gRPC server (finish in-flight RPCs, reject new ones)
+7. Force-stop gRPC server if graceful shutdown didn't complete in time
+8. Call `Stop()` on `CBStopper` services — close database pools, flush metrics, drain message producers
+9. Exit
 
 Tune these values based on your service:
 

howto/signals.md

@@ -31,17 +31,18 @@ When the application receives a signal, ColdBrew executes a multi-step shutdown
 
 1. **`FailCheck(true)`** on services implementing [CBGracefulStopper] — `/readycheck` starts returning failure
 2. **Wait** `GRPC_GRACEFUL_DURATION_IN_SECONDS` (default: 7s) for the load balancer to stop sending traffic
-3. **Shutdown HTTP server** — stop accepting new HTTP requests
-4. **`GracefulStop()` gRPC server** — finish in-flight RPCs, reject new ones
-5. **Force-stop gRPC server** if graceful shutdown didn't complete in time
-6. **`Stop()`** on services implementing [CBStopper] — resource cleanup
-7. **Exit**
+3. **Shutdown admin server** if configured (`ADMIN_PORT`)
+4. **Shutdown HTTP server** — stop accepting new HTTP requests
+5. **`GracefulStop()` gRPC server** — finish in-flight RPCs, reject new ones
+6. **Force-stop gRPC server** if graceful shutdown didn't complete in time
+7. **`Stop()`** on services implementing [CBStopper] — resource cleanup
+8. **Exit**
 
 ## Customizing the shutdown process
 
 Configuring the shutdown process is done by setting the [config] values:
 
-- `SHUTDOWN_DURATION_IN_SECONDS` - Timeout for the entire `Stop()` sequence (default: 15s), covering steps 2-7 above including the drain wait. After this, the process exits regardless.
+- `SHUTDOWN_DURATION_IN_SECONDS` - Timeout for the entire `Stop()` sequence (default: 15s), covering steps 2-8 above including the drain wait. After this, the process exits regardless.
 - `GRPC_GRACEFUL_DURATION_IN_SECONDS` - Duration of step 2 — how long to wait after failing `/readycheck` before stopping servers (default: 7s). This is **included within** `SHUTDOWN_DURATION_IN_SECONDS`, not additional to it.
 - `DISABLE_SIGNAL_HANDLER` - If set to `true`, ColdBrew will not register a signal handler (useful when you want to handle signals yourself).
 

integrations.md

@@ -99,7 +99,7 @@ See the [Metrics How-To](/howto/Metrics/) for details on which metrics are expor
 To configure Sentry, set the following environment variables as defined in [Config]
 - `SENTRY_DSN`: Sentry DSN
 - `ENVIRONMENT`: Environment (e.g. `production`)
-- `RELEASE`: App release (e.g. `v1.0.0`)
+- `RELEASE_NAME`: App release (e.g. `v1.0.0`)
 
 ### Initialising