chore: add CLAUDE.md to repository

.gitignore

@@ -10,5 +10,3 @@
 # Helm
 *.tgz
 charts/*/charts/*.tgz
-
-CLAUDE.md

CLAUDE.md

@@ -0,0 +1,144 @@
+    AGENT SAFEGUARDS (non-negotiable)
+
+Operating principles
+
+1. Prefer clear code over comments.
+   - Use comments only for: non-obvious reasoning, security invariants, protocol quirks, or “why” that code cannot express.
+   - Prefer descriptive names, small functions, and explicit types over commentary.
+
+2. Solve root cause, not band-aids.
+   - Do not add retries/timeouts/logging to hide failures unless the root cause is addressed or explicitly impossible to fix.
+   - If a workaround is necessary, document the root cause and the exact reason it can’t be fixed now.
+
+3. Use idioms of the language and ecosystem.
+   - Follow standard style guides, conventions, directory layout, and tooling.
+   - Avoid clever patterns that fight the ecosystem. Prefer boring, maintainable solutions.
+
+Quality gates
+4) Tests must run after each modification.
+
+- After any functional change, run the relevant test suite locally (or in CI steps) and ensure it passes.
+- If tests cannot run (missing dependency, environment), add or update a runnable test harness or clearly state what is required.
+- Never leave the repo in a state where tests are known failing.
+
+5. Documentation for all features.
+   - Every new feature must have usage docs + one runnable example.
+   - Docs must include intent, flags/config, and failure modes.
+   - Prefer docs that answer user questions (“How do I…”) and include copy/paste snippets.
+
+6. Update CHANGELOG with all changes.
+   - Every user-visible change must be added to CHANGELOG.md under “Unreleased”.
+   - Use categories: Added / Changed / Fixed / Security / Deprecated / Removed.
+   - Mention migration steps if behavior changes.
+   - The `artifacthub.io/changes` annotation in `Chart.yaml` is the chart-level changelog shown to consumers. Only include consumer-facing changes (new features, bug fixes, breaking changes, dependency bumps that affect behavior). Do not add chores, refactoring, CI changes, or test-only changes to it.
+
+Robustness & correctness
+7) Include error handling everywhere it matters.
+
+- Never ignore errors; propagate with context.
+- Wrap/annotate errors so the caller has actionable info.
+- Ensure exit codes/return values are correct and consistent.
+
+8. Test edge cases and invariants.
+   - Add tests for: empty inputs, invalid inputs, boundary values, timeouts, large payloads (reasonable), and concurrency/ordering if relevant.
+   - Include at least one test for each bug fixed to prevent regressions.
+
+Security & safety (important for agentic tooling)
+9) No harmful actions by default.
+
+- Do not delete data, rotate secrets, publish releases, or mutate external systems unless explicitly requested.
+- Treat external calls (network, cloud APIs) as “dangerous”: require explicit opt-in via config/flags.
+
+10. Least privilege and safe defaults.
+
+- Minimize permissions, capabilities, scopes, and access tokens.
+- For Kubernetes artifacts: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation=false, drop ALL capabilities unless justified.
+
+11. No secret leakage.
+
+- Never print tokens, passwords, or full credential material to logs.
+- Redact known secret patterns; avoid echoing env vars that might contain secrets.
+
+12. Deterministic builds and reproducibility.
+
+- Prefer pinned versions, lockfiles, and deterministic packaging.
+- Avoid “download latest at build time” unless necessary.
+
+Change management rules
+13) Chart versions must only be updated via the /release skill.
+
+- **Never** bump `version` in Chart.yaml manually or as part of a regular change.
+- Chart version bumps, changelog updates, and release commits are handled exclusively by the release skill.
+
+14. Small, reviewable diffs.
+
+- Prefer incremental changes with clear commit boundaries.
+- If a refactor is needed, do it in a separate commit/PR before feature changes.
+
+15. Respect existing standards and tooling.
+
+- Use the repo's existing lint/format/test tools (Makefile/package scripts/cargo test/etc.).
+- If tooling is missing, add it in a minimal conventional way.
+
+16. Provide a “How to verify” section in PR descriptions/output.
+
+- Include exact commands: build, lint, unit tests, integration tests (if any).
+
+Agent execution constraints (for local runners / GH actions)
+17) Only modify files that are in-scope for the task.
+
+- Do not reformat unrelated files.
+- Do not introduce new dependencies unless justified.
+
+18. When uncertain, choose the safer option and make it explicit.
+
+- Prefer failing fast with actionable errors over silent fallback.
+- If ambiguity remains, implement a guardrail and document the decision.
+
+19. When really uncertain, ask for help.
+
+- Avoid making assumptions without asking for confirmation.
+
+### Definition of defining an issue
+
+- Gather requirements.
+- Create a github issue.
+- Include a clear description and motivation of the problem.
+- Include:
+  - Expected behavior.
+  - Test cases.
+  - Use cases.
+  - Acceptance criteria.
+
+### Definition of implement issue
+
+- Find the issue in github issues.
+- If not found, inform the user.
+- If found:
+  - Fetch the git origin
+  - Create a branch with the issue number in the name from origin/main.
+  - Implement the issue.
+  - Run all e2e tests.
+  - If during implementation, obvious errors was found in the ooriginating issue, also add a comment to the issue about the fix.
+  - If running from Claude Code or Claude Desktop:
+    - Do NOT create a PR automatically.
+    - Instead, present a summary of changes and let the user decide when to create the PR.
+  - Otherwise (e.g. GitHub Copilot, Junie, or other automated agents):
+    - Create a PR with the issue number in the title.
+    - Make sure the PR passes CI.
+
+### Definition of done
+
+- Code compiles without warnings.
+- Code is linted.
+- Code is formatted.
+- Tests pass.
+- Docs updated.
+- CHANGELOG updated.
+- Edge cases tested.
+- Security posture maintained.
+- Output includes a concise summary of changes + how to verify.
+- For rust code:
+  - All unsafe code is annotated.
+  - Use explicit lifetimes where necessary.
+  - Use clippy lints.