From e88a89f34d686dbeddf4204a9a0d922e56bf7898 Mon Sep 17 00:00:00 2001
From: Hermes Agent <hermes@web1.uscllc.com>
Date: Fri, 22 May 2026 12:01:29 -0500
Subject: [PATCH] fix(framework): remediate Codex review findings in
 VAULT-SECRETS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two should-fix findings from automated Codex review:

1. Vault KV v2 policy path — add explicit path for exact top-level
   `secret/data/k3s/<app>` entry alongside the wildcard `/*` sub-path
   rule. Without the exact path, apps reading the top-level secret get
   permission denied from Vault KV v2 even with the wildcard.

2. Go envconfig example — remove unused `os` import from config.go
   snippet (os was only referenced in a comment). Move the main() usage
   to a separate clearly-labelled main.go block to make both snippets
   copy-paste compilable.

Both fixes mirrored to duplicate path:
  guides/ <-> packages/mosaic/framework/guides/

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 guides/VAULT-SECRETS.md                        | 18 ++++++++++++++----
 .../mosaic/framework/guides/VAULT-SECRETS.md   | 18 ++++++++++++++----
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/guides/VAULT-SECRETS.md b/guides/VAULT-SECRETS.md
index 3692b36..9a797ad 100644
--- a/guides/VAULT-SECRETS.md
+++ b/guides/VAULT-SECRETS.md
@@ -355,7 +355,6 @@ package config
 
 import (
     "fmt"
-    "os"
     "github.com/kelseyhightower/envconfig"
 )
 
@@ -373,10 +372,16 @@ func Load() (*Config, error) {
     }
     return &cfg, nil
 }
+```
 
-// In main():
-// cfg, err := config.Load()
-// if err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }
+In your `main.go`:
+
+```go
+cfg, err := config.Load()
+if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    os.Exit(1)
+}
 ```
 
 ---
@@ -399,7 +404,12 @@ Use this pattern ONLY when a documented dynamic-secrets requirement applies (DB
 vault auth enable approle
 
 # Create a Vault policy for the app
+# Note: KV v2 paths require both the exact path (for the top-level secret) and the
+# wildcard (for sub-paths). Always include both to avoid permission denied errors.
 vault policy write <app>-policy - <<EOF
+path "secret/data/k3s/<app>" {
+  capabilities = ["read"]
+}
 path "secret/data/k3s/<app>/*" {
   capabilities = ["read"]
 }
diff --git a/packages/mosaic/framework/guides/VAULT-SECRETS.md b/packages/mosaic/framework/guides/VAULT-SECRETS.md
index 3692b36..9a797ad 100644
--- a/packages/mosaic/framework/guides/VAULT-SECRETS.md
+++ b/packages/mosaic/framework/guides/VAULT-SECRETS.md
@@ -355,7 +355,6 @@ package config
 
 import (
     "fmt"
-    "os"
     "github.com/kelseyhightower/envconfig"
 )
 
@@ -373,10 +372,16 @@ func Load() (*Config, error) {
     }
     return &cfg, nil
 }
+```
 
-// In main():
-// cfg, err := config.Load()
-// if err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }
+In your `main.go`:
+
+```go
+cfg, err := config.Load()
+if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    os.Exit(1)
+}
 ```
 
 ---
@@ -399,7 +404,12 @@ Use this pattern ONLY when a documented dynamic-secrets requirement applies (DB
 vault auth enable approle
 
 # Create a Vault policy for the app
+# Note: KV v2 paths require both the exact path (for the top-level secret) and the
+# wildcard (for sub-paths). Always include both to avoid permission denied errors.
 vault policy write <app>-policy - <<EOF
+path "secret/data/k3s/<app>" {
+  capabilities = ["read"]
+}
 path "secret/data/k3s/<app>/*" {
   capabilities = ["read"]
 }