review edits

hips/hip-9999.md

@@ -15,7 +15,16 @@ This HIP builds upon [H4HIP: Wasm plugin system](./hip-0026.md) to define how ch
 
 ## Motivation
 
-While the main plugin system HIP enables users to extend Helm's functionality, chart authors ([Application Distributors](https://github.com/helm/community/blob/main/user-profiles.md#2-application-distributor)) need a way to specify which plugins their charts require. This allows charts to use alternative render engines, download protocols, and other plugin-based functionality while ensuring users have the necessary plugins installed.
+While the main plugin system HIP enables users to extend Helm's functionality, chart authors ([Application Distributors](https://github.com/helm/community/blob/main/user-profiles.md#2-application-distributor)) need a way to specify which plugins their charts require. This allows charts to use alternative render engines, download protocols, and other plugin-based functionality while ensuring users have the necessary plugins installed. Enabling much greater control of a chart's operations and flexibility of operation.
+
+The salient difference is that Helm CLI/SDK plugins are controled by the Helm user. Chart defined plugins are defined by the Chart author.
+
+Enabling Helm charts to be extensible aims to enable Chart authors
+
+TODO: System that "just works" / UX
+TODO: Out-of-scope: Operator model: Helm plans to remain a low-level tool
+TODO: Plugin maintainence model (artifact hub, Helm maintained "official", communinity mantained)
+TODO: "existing functionality" -> go plugins
 
 ## Specification
 
@@ -26,14 +35,17 @@ Support for Chart-defined plugins will be added starting in Chart API v3. `Chart
 For the initial release of the new plugin system, chart authors will be able to define custom plugins for the following categories:
 
 - **`getter/v1`** - Download protocols for subcharts beyond HTTP/S and OCI (e.g., S3, Git)
-- **`render/v1`** - Manifest rendering using alternative engines beyond gotemplate (e.g., Pkl, Cue, Kustomize)
+- **`render/v1`** - Manifest rendering using alternative engines beyond gotemplate (e.g., Pkl, Cue, Kustomize, YamlScript, etc)
+- **`values/v1`** - Manage (expand, rewrite, validate) chart rendering values
 
 After the initial plugin system release, the intention is to make it easy to continue adding new chart-defined plugin types to extend additional categories of non-default chart behavior as this becomes desirable. Some examples may be:
 
-- **Values schema validation** (for validating the chart's `values.yaml` file using something other than JSON Schema)
-- **Dependency resolution** (for using a different subchart dependency resolver than the one currently used by Helm)
+- **Values schema management** - expanding, rewriting, validating chart's `values.yaml` file using something other than Helm's inbuilt JSON Schema and subchart values export support
+- **Dependency resolution** - determining and ordering dependencies
+- Values schema validation (for validating the chart's `values.yaml` file using something other than JSON Schema)
+- Dependency resolution (for using a different subchart dependency resolver than the one currently used by Helm)
 
-To plan for forward compatibility, a `minimumHelmVersion` field may be added to allow future plugins to specify the minimum version of Helm that must be used for the chart (or since this is the version of Helm that introduced the new plugin, perhaps this can be auto-detected).
+To plan for forward compatibility, a `minimumHelmVersion` field may be added to Charts to allow future plugins to specify the minimum version of Helm that must be used for the chart (or since this is the version of Helm that introduced the new plugin, perhaps this can be auto-detected).
 
 ### Chart.yaml Plugin Syntax
 
@@ -46,7 +58,26 @@ The `plugins` key is defined as a **list** (not a map). This is critical for `re
 
 Example `Chart.yaml` for Charts v3:
 
+`Chart.yaml` plugins will be defined via a `plugins:` key containing a list of plguins. Enabling ordering of plugin operations. e.g. Chaining chart yaml renderers.
+
+TODO: Do we want to group plugin types? e.g.
+
+```yaml
+  render/v1:
+  - name: pkl
+    repository: oci://ghcr.io/pkl-community/helm-pkl
+    version: 0.1.0
+  - name: kustomize
+    repository: oci://ghcr.io/helm-kustomize
+    version: 0.1.0
+  getter/v1:
+  - name: s3
+    repository: oci://ghcr.io/hypnoglow/helm-s3
+    version: 0.16.3
+```
+
 ```yaml
+---
 apiVersion: v3
 name: my-chart
 version: 1.0.0
@@ -61,12 +92,6 @@ plugins:
     type: getter/v1
     repository: oci://ghcr.io/hypnoglow/helm-s3
     version: 0.16.3
-
-# Renamed from "dependencies" in v2
-subcharts:
-  - name: postgresql
-    version: 12.x.x
-    repository: https://charts.bitnami.com/bitnami
 ```
 
 ### Render/v1 Plugin Specification
@@ -115,7 +140,7 @@ All `render/v1` plugins receive the same Helm built-in objects via JSON serializ
 - `Subcharts` - Metadata about subchart dependencies
 - `Files` - Non-template files accessible to the chart
 - `Capabilities` - Information about the Kubernetes cluster
-- `Template` - Template-specific information (name, base path)
+- `SourceFiles` - Template-specific information (name, base path)
 
 Plugins return rendered Kubernetes manifests as a map of `filename -> content`.
 
@@ -178,21 +203,9 @@ Plugins are referenced by OCI URL in `Chart.yaml` (not packaged within charts).
 
 **Plugin versioning:** The content cache supports multiple versions of the same plugin, allowing different charts to depend on different plugin versions without conflicts.
 
-### Plugin Status: Downloaded vs Installed
+### Chart plugins vs. user (CLI/SDK) plugins
 
-Plugins can exist in two states:
-
-| Status         | Description                                                                   |
-| -------------- | ----------------------------------------------------------------------------- |
-| **Installed**  | Globally installed via `helm plugin install`, available for all Helm commands |
-| **Downloaded** | Fetched for chart-defined use, only available when chart specifies it         |
-
-**Storage locations:**
-
-| Type                       | Path                                       | Purpose                                       |
-| -------------------------- | ------------------------------------------ | --------------------------------------------- |
-| Global install destination | `$PLUGINS_DIR/<name>/`                     | Final location for installed plugins          |
-| Chart-defined tarball      | `$HELM_CACHE_HOME/content/{digest}.plugin` | Content-addressable cache (loaded at runtime) |
+Chart plugins are not visible to the CLI/SDK plugin registry and cannot be managed via `helm plugin install/uninstall`. They are only loaded and used when a chart explicitly specifies them in `Chart.yaml`.
 
 Chart-defined plugins are cached as tarballs in the content-addressable cache and loaded directly into memory at runtime (no disk extraction required). The Wasm runtime loads plugin binaries from the tarball bytes.
 
@@ -211,6 +224,8 @@ Chart-defined plugins are cached as tarballs in the content-addressable cache an
 
 **Installing a downloaded plugin globally (future enhancement):**
 
+TODO: disagree with this section
+
 ```bash
 # After downloading via helm dependency update, install globally:
 helm plugin install --from-download pkl-render 0.2.0
@@ -223,6 +238,8 @@ helm plugin install --from-download pkl-render 0.2.0
 
 **Plugin loading precedence:**
 
+TODO: disagree with this section
+
 When a chart specifies a plugin, Helm looks in this order:
 
 1. **Content cache first:** `$HELM_CACHE_HOME/content/{digest}.plugin` (loaded directly from tarball)
@@ -232,6 +249,8 @@ If the fallback path is used, the installed plugin's version **must match** the
 
 **`helm plugin list` enhancements:**
 
+TODO: disagree with this section
+
 To support chart-defined plugins, `helm plugin list` will be extended:
 
 ```bash
@@ -320,61 +339,6 @@ A reference implementation has been developed to validate this design:
 - **Reference plugins**: [scottrigby/ref-hip-chart-defined-plugins](https://github.com/scottrigby/ref-hip-chart-defined-plugins) - Wasm render/v1 plugins using Extism Go PDK
 - **Example charts**: [scottrigby/ref-hip-chart-defined-plugins/charts](https://github.com/scottrigby/ref-hip-chart-defined-plugins/tree/main/charts) - Demonstrates Chart.yaml with plugins list
 
-## Reference Links
-
-- [HIP PR](https://github.com/helm/community/pull/400)
-- [Helm Built-in Objects](https://helm.sh/docs/chart_template_guide/builtin_objects/)
-- [Pkl Helm Discussion](https://github.com/apple/pkl/discussions/1190#discussioncomment-15262863)
-
-## How to teach this
-
-- Create examples of Chart-defined plugins for the new plugin system that contributors can use as a model for their own plugins
-  - Chart-defined plugin example. The Gotemplate `render` plugin will have already created
-- Write concise and easy to follow documentation for chart-defined plugins
-- Write a blog post outlining how chart authors will benefit from chart-defined plugins, which can link to the documentation and these examples
-- Create a presentation to propose for conference talks as another communition channel to make the community aware of chart-defined plugins
-
-## Open issues
-
-_Points still being decided/discussed._
-
-### 1. Gotemplate as Plugin for Charts v3
-
-Should gotemplate rendering be provided via a Helm-maintained plugin for Chart API v3 (rather than built-in)?
-
-**Pros:**
-
-- Cleaner architecture aligning with plugin-based design
-- Enables organic deprecation: as chart authors adopt alternative renderers, gotemplate phases out naturally
-- Separate deprecation cycle from Helm/Charts API major versions
-- Plugin could be separate Helm subproject with independent release cycle
-
-**Cons:**
-
-- Users must download plugin for functionality assumed built-in for Charts v2
-- Could surprise users expecting gotemplate to "just work"
-
-**Mitigation:**
-
-- Users already assume subchart dependencies must be downloaded
-- Plugins cached by version globally and shared across charts
-- Can be downloaded ahead of time for airgap scenarios
-- Small trade-off for much more flexible chart-defined plugin functionality
-
-**Decision needed:** Should this be part of initial Charts v3 release or introduced later?
-
-### 2. ArtifactHub Integration
-
-How should chart-defined plugins be discovered and listed on ArtifactHub?
-
-**Considerations:**
-
-- Plugin subtypes (render, getter, etc.) as entry properties
-- Unified catalog format across artifact kinds
-- Search/filter by plugin type
-
-**Decision needed:** ArtifactHub schema for chart-defined plugins?
-
 ### 3. SDK Considerations
 
 The Helm SDK is used by various tools and platforms beyond the CLI, including: