Update Docs Workflow

The Helm documentation workflow has three parts: update the feature manifest, update the audience-specific docs, and pass CI validation.

Workflow for every feature

1. Add or update the feature entry in apps/helm-docs/features/helm-features.json.
2. Decide whether the feature affects clients, internal users, or both.
3. Add the relevant docs paths to the feature entry.
4. Run bun run docs:helm:scaffold if a new feature doc page is needed.
5. Write the docs in the appropriate section:
   • Client docs explain user-visible behavior, expectations, statuses, and outputs.
   • Internal docs explain operating procedure, review gates, integrations, failure modes, and escalation.
6. Run bun run docs:helm:check.
7. Run bun run build:helm-docs.

CI guardrail

The Helm docs workflow checks pull requests that touch Helm feature areas. If a PR changes Helm app code, backend routes, core logic, document templates, jobs, integrations, or Supabase migrations, it must also update the docs content, docs workflow script, or feature manifest.

The guardrail does not prove that the wording is perfect. It ensures the PR includes a documentation decision. Reviewers should still read the docs changes for accuracy.

Feature manifest contract

Each feature entry should include:

Every referenced MDX file must include {/* feature: feature-id */} so reviewers can trace feature coverage from the manifest to the docs page.

Review loop

Use this loop before merging documentation:

1. Check accuracy against the current Helm UI and API behavior.
2. Check audience separation: client docs should not expose internal-only procedure or secrets.
3. Check actionability: internal docs should say what to do, when to do it, and when to escalate.
4. Check static build output with bun run build:helm-docs.
5. Check feature traceability with bun run docs:helm:check.