chore(workflows): enhance permissions for future artifact publication and clarify comments

docs(readme): add advanced usage section for route pattern matching and dynamic segment mismatches
docs(metrics): refine build tag guidance for Prometheus and Datadog exporters
fix(eventlogger): clarify ShutdownDrainTimeout behavior for graceful shutdown

Author: intel352

.github/workflows/cli-release.yml

@@ -25,7 +25,8 @@ env:
   GO_VERSION: '^1.25'
 
 permissions:
-  contents: write
+  contents: write   # tagging & attaching release assets
+  packages: write   # allow publishing to registries if added later
 
 jobs:
   prepare:

.github/workflows/module-release.yml

@@ -1,6 +1,11 @@
 name: Module Release
 run-name: Module Release for ${{ inputs.module || github.event.inputs.module }} - ${{ inputs.releaseType || github.event.inputs.releaseType }}
 
+# Minimal global permissions; individual jobs do not request escalation beyond content/package writes.
+permissions:
+  contents: write   # create tags & push version bumps
+  packages: write   # future-proof for publishing module artifacts
+
 on:
   workflow_dispatch:
     inputs:

.github/workflows/release-all.yml

@@ -12,12 +12,12 @@ on:
         default: patch
 
 permissions:
-  # Need contents write for tagging/releases, actions write for workflow dispatches,
-  # pull-requests & checks write are required by the called auto-bump-modules workflow
-  contents: write
-  actions: write
-  pull-requests: write
-  checks: write
+  # Principle of least privilege: core orchestration requires these scopes. No others granted globally.
+  contents: write        # create tags/releases
+  actions: write         # dispatch called workflows
+  pull-requests: write   # create/update bump PRs
+  checks: write          # update status checks from composite jobs
+  packages: write        # allow future artifact/package publication without further scope changes
 
 jobs:
 

modules/chimux/README.md

@@ -196,6 +196,33 @@ The chimux module will automatically discover and use any registered `Middleware
 
 ## Advanced Usage
 
+### Route Pattern Matching & Dynamic Segment Mismatches
+
+The underlying Chi router matches the *pattern shape* – a registered route with a
+dynamic segment (e.g. `/api/users/{id}`) matches `/api/users/123` as expected, but a
+request to `/api/users/` (trailing slash, missing segment) or `/api/users` (no trailing
+slash, missing segment) will **not** invoke that handler. This is intentional: Chi treats
+`/api/users` and `/api/users/` as distinct from `/api/users/{id}` to avoid accidental
+shadowing and ambiguous parameter extraction.
+
+If you want both collection and entity semantics, register both patterns explicitly:
+
+```go
+router.Route("/api/users", func(r chimux.Router) {
+    r.Get("/", listUsers)        // GET /api/users
+    r.Post("/", createUser)      // POST /api/users
+    r.Route("/{id}", func(r chimux.Router) { // GET /api/users/{id}
+        r.Get("/", getUser)     // (Chi normalizes without extra segment; trailing slash optional when calling)
+        r.Put("/", updateUser)
+        r.Delete("/", deleteUser)
+    })
+})
+```
+
+For optional trailing segments, prefer explicit duplication instead of relying on
+middleware redirects. Keeping patterns explicit makes route introspection, dynamic
+enable/disable operations, and emitted routing events deterministic.
+
 ### Adding custom middleware to specific routes
 
 ```go

modules/eventbus/metrics_exporters.go

@@ -27,10 +27,12 @@ package eventbus
 //   prometheus_collector_stub.go -> //go:build !prometheus
 // This keeps mainline source simple while letting consumers tailor binaries without forking.
 //
-// Build tag guidance: To exclude Prometheus support, supply -tags "!prometheus" (assuming
-// you split the collector into tagged files as described). Similarly a datadog specific
-// exporter could live behind a datadog build tag. We keep a unified file here until a
-// concrete need for binary size reduction or dependency trimming warrants the split.
+// Build tag guidance: To exclude Prometheus support, supply -tags "!prometheus" (after
+// splitting into prometheus_collector.go / prometheus_collector_stub.go). Likewise a
+// Datadog exporter can live behind a `datadog` tag. We intentionally keep everything in a
+// single file until (a) dependency graph or (b) binary size pressure justifies tag split.
+// This documents the approach so consumers understand the future direction without
+// misinterpreting current unified source as a lack of modularity.
 
 import (
 	"context"

modules/eventlogger/config.go

@@ -41,12 +41,11 @@ type EventLoggerConfig struct {
 	// When false, the module will not emit com.modular.eventlogger.stopped to avoid races with shutdown.
 	ShutdownEmitStopped bool `yaml:"shutdownEmitStopped" default:"true" desc:"Emit logger stopped operational event on Stop"`
 
-	// ShutdownDrainTimeout specifies how long Stop() should wait for in-flight events to drain.
-	// Zero or negative duration means "wait indefinitely" (Stop blocks until all events processed).
-	// This allows operators to explicitly choose between a bounded shutdown and a fully
-	// lossless drain. A very large positive value is NOT treated specially—only <=0 triggers
-	// the indefinite behavior.
-	ShutdownDrainTimeout time.Duration `yaml:"shutdownDrainTimeout" default:"2s" desc:"Maximum time to wait for draining event queue on Stop. Zero or negative = unlimited wait."`
+	// ShutdownDrainTimeout controls graceful shutdown behavior for in‑flight events.
+	// If > 0: Stop() waits up to the specified duration then returns (remaining events may be dropped).
+	// If <= 0: Stop() waits indefinitely for a full drain (lossless shutdown) unless the parent context cancels.
+	// This explicit <= 0 contract avoids ambiguous huge timeouts and lets operators choose bounded vs. lossless.
+	ShutdownDrainTimeout time.Duration `yaml:"shutdownDrainTimeout" default:"2s" desc:"Max drain wait on Stop; <=0 = wait indefinitely for all events"`
 }
 
 // OutputTargetConfig configures a specific output target for event logs.