docs(helm): document supported values and add usage examples

README.md

@@ -124,6 +124,8 @@ helm install openab openab/openab \
   --set-string 'agents.kiro.slack.allowedChannels[0]=C0123456789'
 ```
 
+For additional Helm values such as `fullnameOverride`, `nameOverride`, `envFrom`, and `agentsMd`, see [charts/openab/README.md](charts/openab/README.md).
+
 ### 3. Authenticate (first time only)
 
 ```bash

charts/openab/README.md

@@ -0,0 +1,96 @@
+# openab Helm Chart
+
+This chart deploys one or more OpenAB agents on Kubernetes.
+
+## Common Values
+
+This page highlights commonly used values and deployment patterns. For the complete list of supported options and defaults, run `helm show values openab/openab` or inspect [`values.yaml`](values.yaml).
+
+### Release naming
+
+| Value | Description | Default |
+|-------|-------------|---------|
+| `nameOverride` | Override the chart name portion used in generated resource names. For per-agent resource names, use `agents.<name>.nameOverride`. | `""` |
+| `fullnameOverride` | Override the full generated release name for chart resources. Useful when deploying multiple instances with predictable names. | `""` |
+
+### Agent values
+
+Each agent lives under `agents.<name>`.
+
+| Value | Description | Default |
+|-------|-------------|---------|
+| `discord.botToken` | Discord bot token for the agent. | `""` |
+| `discord.allowedChannels` | Channel allowlist. Use `--set-string` for Discord IDs. | `["YOUR_CHANNEL_ID"]` |
+| `discord.allowedUsers` | User allowlist. Empty = allow all users by default. Use `--set-string` for Discord IDs. | `[]` |
+| `discord.allowDm` | Whether the Discord bot responds to direct messages. | `false` |
+| `discord.allowBotMessages` | Controls whether bot messages can trigger replies. | `"off"` |
+| `discord.trustedBotIds` | Optional bot ID allowlist when bot-message replies are enabled. | `[]` |
+| `slack.enabled` | Enable the Slack adapter for the agent. | `false` |
+| `slack.botToken` | Slack Bot User OAuth token. | `""` |
+| `slack.appToken` | Slack App-Level token for Socket Mode. | `""` |
+| `slack.allowedChannels` | Slack channel allowlist. Empty means allow all channels by default. | `[]` |
+| `slack.allowedUsers` | Slack user allowlist. Empty means allow all users by default. | `[]` |
+| `nameOverride` | Override this agent's generated resource name. | `""` |
+| `workingDir` | Working directory and HOME inside the container. | `"/home/agent"` |
+| `env` | Inline environment variables passed to the agent process. | `{}` |
+| `envFrom` | Additional environment sources from existing Secrets or ConfigMaps. | `[]` |
+| `pool.maxSessions` | Maximum concurrent ACP sessions for the agent. | `10` |
+| `pool.sessionTtlHours` | Idle session TTL in hours. | `24` |
+| `reactions.enabled` | Enable status reactions. | `true` |
+| `reactions.removeAfterReply` | Remove status reactions after the agent replies. | `false` |
+| `reactions.toolDisplay` | Tool display verbosity: `full`, `compact`, or `none`. | `"full"` |
+| `stt.enabled` | Enable voice-message speech-to-text. | `false` |
+| `stt.apiKey` | API key for the speech-to-text provider. | `""` |
+| `stt.model` | STT model name. | `"whisper-large-v3-turbo"` |
+| `stt.baseUrl` | STT API base URL. | `"https://api.groq.com/openai/v1"` |
+| `gateway.enabled` | Enable the gateway config block for webhook-based platforms. | `false` |
+| `gateway.deploy` | Deploy the gateway Deployment and Service. | `true` |
+| `cron.usercronEnabled` | Enable user-provided cron configuration. | `false` |
+| `cronjobs` | Config-driven scheduled messages for an agent. | `[]` |
+| `persistence.enabled` | Enable persistent storage for auth and settings. | `true` |
+| `persistence.existingClaim` | Reuse an existing PVC instead of creating one. | `""` |
+| `agentsMd` | Contents of `AGENTS.md` mounted into the working directory. | `""` |
+| `extraInitContainers` | Additional init containers for the agent pod. | `[]` |
+| `extraContainers` | Additional sidecar containers for the agent pod. | `[]` |
+| `extraVolumeMounts` | Additional volume mounts for the main agent container. | `[]` |
+| `extraVolumes` | Additional volumes for the agent pod. | `[]` |
+
+## Examples
+
+### Override generated names
+
+```bash
+helm install prod openab/openab \
+  --set fullnameOverride=my-openab \
+  --set-literal agents.kiro.discord.botToken="$DISCORD_BOT_TOKEN" \
+  --set-string 'agents.kiro.discord.allowedChannels[0]=YOUR_CHANNEL_ID'
+```
+
+This makes generated resource names use `my-openab` (for example `my-openab-kiro`) instead of the default `prod-openab`.
+
+### Load credentials with `envFrom`
+
+```yaml
+agents:
+  kiro:
+    envFrom:
+      - secretRef:
+          name: openab-agent-secrets
+      - configMapRef:
+          name: openab-agent-config
+```
+
+This is useful for credentials such as `GH_TOKEN` without storing them directly in Helm values.
+
+### Provide `AGENTS.md` with `--set-file`
+
+```bash
+helm install openab openab/openab \
+  --set-literal agents.kiro.discord.botToken="$DISCORD_BOT_TOKEN" \
+  --set-string 'agents.kiro.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
+  --set-file agents.kiro.agentsMd=./AGENTS.md
+```
+
+### Discord ID precision warning
+
+Discord IDs must be set with `--set-string`, not `--set`. Otherwise Helm may coerce them into numbers and lose precision.

charts/openab/values.yaml

@@ -4,6 +4,13 @@ image:
   tag: ""
   pullPolicy: IfNotPresent
 
+# Chart-level name override used in generated resource names.
+# For per-agent overrides, use agents.<name>.nameOverride.
+nameOverride: ""
+
+# Override the full release name used in generated resource names.
+fullnameOverride: ""
+
 podSecurityContext:
   runAsNonRoot: true
   runAsUser: 1000
@@ -106,6 +113,7 @@ agents:
     #     allowedUsers: []
     #   workingDir: /home/agent
     #   env: {}
+    #   # Load env vars from existing Secrets or ConfigMaps, e.g. GH_TOKEN.
     #   envFrom: []
     #   pool:
     #     maxSessions: 10
@@ -177,6 +185,7 @@ agents:
       # maxBotTurns: 20
     workingDir: /home/agent
     env: {}
+    # Load env vars from existing Secrets or ConfigMaps, e.g. GH_TOKEN.
     envFrom: []
     pool:
       maxSessions: 10
@@ -274,6 +283,7 @@ agents:
       existingClaim: ""  # set to reuse an existing PVC (skips PVC creation)
       storageClass: ""
       size: 1Gi  # defaults to 1Gi if not set
+    # Mount a custom AGENTS.md file. Useful with --set-file.
     # ⚠️ When set, this ConfigMap mount shadows any file at the same path on the PVC.
     # The PVC file is NOT deleted but becomes invisible to the agent. Remove agentsMd to restore.
     agentsMd: ""