feat(example): add optional gVisor, nodeSelector, NetworkPolicy and provider keys (#21)

Add opt-in hardening to the agents-as-a-service example:
- commented runtimeClassName/nodeSelector fields for sandboxes and Deployments
- optional sandbox NetworkPolicy plus exposure-variant policies
- optional dsh-provider-keys-extra Secret for extra provider keys
- docs/optional-hardening.md with verification, caveats and rollback

The base walkthrough stays portable; no gateway code, routes or auth changed.

Co-authored-by: SREDevOpsAgents <agents@sredevops.org>

docs/examples.md

@@ -18,6 +18,9 @@ examples/<name>/
 |                                 #   ordered steps, troubleshooting, cleanup
 +-- manifests/                    # required
 |   +-- NN-*.yaml                 #   numbered top-level manifests, plain kubectl
+|   +-- optional/                 #   optional opt-in manifests, applied by path
+|       +-- README.md             #     required when optional/ exists
+|       +-- <feature>/NN-*.yaml   #     e.g. network-policy/
 |   +-- exposure/                 #   optional exposure variants
 |       +-- README.md             #     required when exposure/ exists
 |       +-- <variant>/NN-*.yaml   #     e.g. ingress/, gateway-api-sso/
@@ -41,6 +44,8 @@ examples/<name>/
 - a `*.yaml` file sits at the example root instead of under `manifests/`;
 - `manifests/exposure/` exists without a `manifests/exposure/README.md` describing
   the variants;
+- `manifests/optional/` exists without a `manifests/optional/README.md`
+  describing the opt-in manifests;
 - a subdirectory with a `Dockerfile` has no `README.md`;
 - a file in `scripts/` is not executable.
 
@@ -68,7 +73,12 @@ make check
   command; real values are generated per install.
 - **Cluster-specific state stays out.** Node affinity, replica counts tuned for a
   cluster, and similar fields belong in a local patch, not in the shipped
-  manifest.
+  manifest. Optional scheduler/runtime hints may ship **commented out** with
+  placeholder labels; they must not be active.
+- **Optional manifests are opt-in.** Put them under
+  `manifests/optional/<feature>/`, document them in
+  `manifests/optional/README.md`, and apply them by path. The top-level
+  `kubectl apply -f manifests/` is non-recursive and does not apply them.
 - **Placeholders are explicit.** Hostnames, GitHub orgs and TLS material use
   values like `dsh.example.com` / `your-github-org` with a TODO comment.
 

docs/main-image.md

@@ -80,6 +80,28 @@ The entrypoint is `tini -- /usr/local/bin/dsh-entrypoint`:
 The image also sets `NODE_ENV=production`, `HOME=/home/node`, and a `PATH` that
 includes `/app/node_modules/.bin`.
 
+### Provider credentials
+
+DSH resolves provider API keys from the environment when no stored credential
+exists. The packaged provider catalog maps each provider to its standard
+environment name. Commonly used names:
+
+`DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `NVIDIA_API_KEY`,
+`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`,
+`MISTRAL_API_KEY`, `TOGETHER_API_KEY`, `CEREBRAS_API_KEY`,
+`AI_GATEWAY_API_KEY`, `HF_TOKEN`.
+
+Use `GEMINI_API_KEY` for Google Gemini (not `GOOGLE_API_KEY`), `HF_TOKEN` for
+Hugging Face, and `AI_GATEWAY_API_KEY` for the Vercel AI Gateway. Inject keys
+with `-e`/`--env-file` in Docker or a Secret + `envFrom` in Kubernetes; never
+bake them into the image.
+
+A key saved through DSH's credential store (`$DSH_HOME/.credentials.yaml`) wins
+over the environment. The
+[agents-as-a-service example](../examples/dsh-agents-as-a-service/docs/optional-hardening.md)
+documents the optional `dsh-provider-keys-extra` Secret and the pod-refresh
+procedure.
+
 ### Ports, volumes and signals
 
 | Item | Value | Notes |