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

[chihkang]

Summary

This PR improves the Helm chart documentation by adding several supported but currently undocumented values to the values reference and README.

Users can already rely on these options in practice, but today they are difficult to discover unless they inspect the chart templates directly. This change makes the chart easier to use and reduces trial-and-error during deployment.

Closes #163.

Changes

• add fullnameOverride to values.yaml
• add nameOverride to values.yaml
• document envFrom in values.yaml comments and chart docs
• document agentsMd usage with --set-file
• document the discord.allowedChannels --set-string requirement more prominently
• add a chart-level Helm values reference with practical examples
• link the main README Helm install section to the chart values reference

Why

The chart already supports these configuration paths, but they are not clearly documented. That creates unnecessary friction for users, especially for:

• multi-instance deployments
• secret-based environment injection
• large AGENTS.md configurations
• Discord channel ID configuration

Notes

This PR is documentation-focused and does not change chart behavior. It only makes existing supported options easier to discover and use.

Testing

• reviewed chart templates to confirm the documented values are already supported
• documentation change only; helm CLI was not available in the local environment for helm lint

[chaodu-agent]

🟡 Needs Update — Good intent, but stale + merge conflicts + incomplete coverage.

Baseline Check (Step 0)

Field	Value
State	OPEN
Mergeable	CONFLICTING
Created	2026-04-13 (18 days ago)
Changes	+78 / -0, docs only
Labels	p3, closing-soon

Main branch status: No charts/openab/README.md exists — PR creates it fresh. ✅ However, values.yaml has changed significantly since April 13 with ~19 feature commits touching the chart.

Four-Question Framework

1. What problem does it solve?
The Helm chart supports many values only discoverable by reading templates directly. This PR adds a chart-level README with values reference table and practical usage examples.

2. How does it solve it?

• Creates charts/openab/README.md with values table + 4 usage examples
• Adds top-level nameOverride and fullnameOverride defaults to values.yaml
• Adds inline comments for envFrom and agentsMd

3. What was considered?
Documentation-only, no behavior change. Contributor reviewed templates to confirm documented values are supported.

4. Is it the best approach?
Sound approach — chart-level README is standard Helm convention. But execution has gaps due to staleness.

Traffic Light

🟢 INFO

• Correct identification of undocumented gap (nameOverride/fullnameOverride missing from values.yaml)
• Practical examples (envFrom, --set-file agentsMd, Discord ID precision warning)
• Standard Helm convention for chart docs

🟡 NIT

1. Values table very incomplete — Documents only ~8 values. Actual chart has 27+ agent-level keys including slack.*, gateway.*, reactions.*, stt.*, cron.*, persistence.*, pool.*, extraInitContainers, extraContainers, allowBotMessages, trustedBotIds, allowDm, maxBotTurns, etc.
2. Consider helm-docs for auto-generation from values.yaml comments.

🔴 SUGGESTED CHANGES

1. Merge conflict must be resolved — values.yaml has changed significantly since April 13.
2. Stale documentation risk — Since PR opened, main gained: gateway templates, maxBotTurns, allowDm, reactions.toolDisplay, cron/cronjobs, extraContainers, Slack adapter config, allowBotMessages/trustedBotIds. The "values reference" title is misleading at ~15% coverage.
3. closing-soon label — Missing Discord Discussion URL. Will auto-close in 3 days unless addressed.

Reviewed by 超渡法師 🔃 chaodu Backlog triage

[chaodu-agent]

超渡法師 Review — PR #280

1. What problem does it solve?

The Helm chart supports several useful values (fullnameOverride, nameOverride, envFrom, agentsMd, --set-string for Discord IDs) but none were documented in a discoverable way. Users had to read _helpers.tpl and template source to find them.

2. How does it solve it?

• New charts/openab/README.md — 66-line values reference with tables and three practical examples (name override, envFrom for secrets, --set-file for AGENTS.md, Discord ID precision warning).
• charts/openab/values.yaml — adds nameOverride: "" and fullnameOverride: "" as top-level defaults (consumed by _helpers.tpl but never declared).
• README.md — cross-reference linking to the chart README from Quick Start.

3. What was considered?

Docs-only, no behavior changes. Contributor reviewed chart templates to confirm all documented values are already functional.

4. Is this the best approach?

Clean, well-scoped docs PR that directly addresses every item in issue #163. Surfacing existing values in values.yaml defaults is standard Helm convention.

---

Traffic Light

🟢 INFO — Well done

• nameOverride/fullnameOverride added to values.yaml — verified that _helpers.tpl on main already consumes both. helm show values will now surface them.
• The --set-string precision warning for Discord IDs is a real footgun; documenting it prominently is valuable.
• envFrom example correctly shows both secretRef and configMapRef patterns.
• Cross-reference from root README to chart README is a nice touch.

🟡 NIT

1. Values table is incomplete — The table omits commonly-used agent values already in values.yaml: pool, reactions, persistence, stt, gateway, slack, allowBotMessages, trustedBotIds. The table doesn't need to be exhaustive, but a note like "For the full list, run helm show values openab/openab" would set expectations.
2. Chart-level vs agent-level nameOverride — The existing commented-out agent blocks already have a per-agent nameOverride. A one-line comment like # Chart-level name override (for per-agent override, see agents.<name>.nameOverride) would prevent confusion.
3. allowedUsers default — Shown as [] with description "Empty means allow all users." Consider making this clearer: "Empty = allow all (default)".

---

Verdict

🟢 Looks good — Clean docs-only PR. The NITs above are minor improvements. No blocking issues.