docs: add instructions for agents

Signed-off-by: Emilien Escalle <[email protected]>

Author: neilime

AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — agent instructions and operational contract
+
+This file is written for automated coding agents (for example: Copilot coding agents). It exists to provide a concise operational contract and guardrails for agents working in this repository. It is not the canonical source for design or style rules. Those live in the developer documentation linked below.
+
+## Organization-wide guidelines (required)
+
+- Follow the prioritized shared instructions in [hoverkraft-tech/.github/AGENTS.md](https://github.com/hoverkraft-tech/.github/blob/main/AGENTS.md) before working in this repository.
+
+## Quick Start
+
+This project contains **opinionated GitHub Actions and reusable workflows** to standardize OCI image build, publication, and Helm chart promotion pipelines. For comprehensive documentation, see the main [README.md](README.md).
+
+### Key Sections to Reference
+
+- **[Overview](README.md#overview)** – Project purpose and scope
+- **[Actions](README.md#actions)** – Catalog of container-focused actions grouped by category
+- **[Reusable Workflows](README.md#reusable-workflows)** – Orchestration playbooks for common CI tasks
+- **[Contributing](README.md#contributing)** – Contribution guidelines, action structure patterns, and development standards
+- **[Development Workflow](README.md#development-workflow)** – Commands for linting, testing, and local development
+
+## Agent-Specific Development Patterns
+
+### Critical Workflow Knowledge
+
+```bash
+# Essential commands for development
+make lint                 # Run the dockerized Super Linter
+make lint-fix             # Attempt auto-fixes for lint findings
+make test-build-application  # Build and push the sample test application image
+make test-ct-install         # Validate Helm charts via chart-testing
+```
+
+For detailed documentation on each action and workflow, refer to the individual readme files linked in the main [README.md](README.md).

README.md

@@ -10,14 +10,18 @@
 
 </div>
 
-Opinionated GitHub Actions and workflows for continuous integration in container (OCI) context
-
 ---
 
+## Overview
+
+Opinionated GitHub Actions and reusable workflows to build, test, sign, and distribute container images and Helm charts. The goal is to offer a consistent supply-chain friendly pipeline for OCI assets managed within GitHub Actions.
+
 ## Actions
 
 ### Docker
 
+_Actions that operate on OCI images across their build, metadata, and lifecycle management phases._
+
 #### - [Build image](actions/docker/build-image/README.md)
 
 #### - [Create images manifests](actions/docker/create-images-manifests/README.md)
@@ -32,6 +36,8 @@ Opinionated GitHub Actions and workflows for continuous integration in container
 
 ### Helm
 
+_Actions dedicated to packaging, validating, and publishing Helm charts for Kubernetes deployments._
+
 #### - [Generate chart documentation](actions/helm/generate-docs/README.md)
 
 #### - [Parse chart URI](actions/helm/parse-chart-uri/README.md)
@@ -42,13 +48,77 @@ Opinionated GitHub Actions and workflows for continuous integration in container
 
 ## Reusable Workflows
 
+_Orchestrated workflows you can plug directly into repositories to automate container-focused CI routines._
+
 ### - [Docker build images](.github/workflows/docker-build-images.md)
 
 ### - [Prune pull requests images tags](.github/workflows/prune-pull-requests-images-tags.md)
 
 ## Contributing
 
-👍 If you wish to contribute to this project, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file, PRs are Welcome !
+Contributions are welcome! Please review the [contributing guidelines](CONTRIBUTING.md) before opening a PR.
+
+### Action Structure Pattern
+
+All actions follow a consistent layout:
+
+```text
+actions/{category}/{action-name}/
+├── action.yml          # Action definition with inputs/outputs
+├── README.md           # Usage documentation and examples
+└── index.js / scripts  # Optional Node.js helpers (when required)
+```
+
+### Development Standards
+
+#### Action Definition Standards
+
+1. **Consistent branding**: Use `author: hoverkraft` with `color: blue` and a meaningful `icon`.
+2. **Pinned dependencies**: Reference third-party actions via exact SHAs to guarantee reproducibility.
+3. **Input validation**: Validate critical inputs early within composite steps or supporting scripts.
+
+#### Container Delivery Patterns
+
+- Prefer multi-architecture builds via `docker buildx build` with explicit `--platform` lists.
+- Surface provenance metadata through outputs (`image-name`, `digest`, etc.) to unblock downstream jobs.
+- Keep secrets and registry credentials in GitHub environments or organization secrets—never hardcode them.
+
+### Development Workflow
+
+#### Linting & Testing
+
+```bash
+make lint                 # Run the dockerized Super Linter
+make lint-fix             # Attempt auto-fixes for lint findings
+
+# Container & Helm validation helpers
+make test-build-application  # Build and push the sample test application image
+make test-ct-install         # Validate Helm charts via chart-testing
+```
+
+#### File Conventions
+
+- **Dockerfile**: Provides the Super Linter environment with UID/GID passthrough for local dev parity.
+- **Tests**: Located in `tests/` with fixtures for container builds and chart-testing scenarios.
+- **Workflows**: Reusable definitions live in `.github/workflows/`; internal/private workflows are prefixed with `__`.
+
+#### Action Development Conventions
+
+1. **Idempotent steps**: Ensure actions can run multiple times without leaving residual state in the workspace.
+2. **Logging**: Use structured logs with clear prefixes (`[build-image]`, `[helm-test-chart]`, …) to simplify debugging.
+3. **Security**: Avoid shell interpolation with untrusted inputs; prefer parameterized commands or `set -euo pipefail` wrappers.
+
+#### JavaScript Development Patterns
+
+- Encapsulate reusable logic in modules under the action directory (for example, `actions/docker/prune-pull-requests-image-tags/index.js`).
+- Prefer async/await with explicit error handling when interacting with the GitHub API or filesystem.
+- Centralize environment variable parsing and validation to keep composite YAML lean.
+
+#### Helm Testing Patterns
+
+- Use the chart fixtures under `tests/charts/` to exercise Helm-focused actions.
+- Maintain `Chart.lock` files alongside `Chart.yaml` to document dependency revisions.
+- Commit `ci/empty-values.yaml` templates for creating scenario-specific overrides.
 
 ## Author
 
@@ -59,5 +129,8 @@ Opinionated GitHub Actions and workflows for continuous integration in container
 
 ## License
 
-📝 Copyright © 2023 [Hoverkraft <[email protected]>](https://hoverkraft.cloud).<br />
-This project is [MIT](LICENSE) licensed.
+This project is licensed under the MIT License.
+
+SPDX-License-Identifier: MIT
+
+© 2025 hoverkraft-tech. See [LICENSE](LICENSE) for details.

tests/charts/application/README.md

@@ -6,9 +6,9 @@ A Helm chart for Kubernetes
 
 ## Requirements
 
-| Repository                         | Name  | Version |
-| ---------------------------------- | ----- | ------- |
-| https://charts.bitnami.com/bitnami | mysql | 14.0.3  |
+| Repository                           | Name  | Version |
+| ------------------------------------ | ----- | ------- |
+| <https://charts.bitnami.com/bitnami> | MySQL | 14.0.3  |
 
 ## Values
 

tests/charts/umbrella-application/README.md

@@ -6,10 +6,10 @@ An umbrella Helm chart for Kubernetes
 
 ## Requirements
 
-| Repository                         | Name            | Version |
-| ---------------------------------- | --------------- | ------- |
-| file://./charts/app                | app             | 0.0.0   |
-| https://charts.bitnami.com/bitnami | database(mysql) | 14.0.3  |
+| Repository                           | Name            | Version |
+| ------------------------------------ | --------------- | ------- |
+| file://./charts/app                  | app             | 0.0.0   |
+| <https://charts.bitnami.com/bitnami> | database(MySQL) | 14.0.3  |
 
 ## Values