From 555e755d9c2bd927000313e6f324c5cf12fe4de0 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 08:11:51 -0400
Subject: [PATCH 001/131] v1beta1 start

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 282 ++++++++++++++++++++++++++++++++++
 0051-v1beta1-schema/zep.yaml  |  34 ++++
 2 files changed, 316 insertions(+)
 create mode 100644 0051-v1beta1-schema/README.md
 create mode 100644 0051-v1beta1-schema/zep.yaml

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
new file mode 100644
index 0000000..7074e9f
--- /dev/null
+++ b/0051-v1beta1-schema/README.md
@@ -0,0 +1,282 @@
+<!--
+**Note:** When your ZEP is complete, all of these comment blocks should be removed.
+
+To get started with this template:
+
+- [ ] **Create an issue in zarf-dev/proposals.**
+  When creating a proposal issue, complete all fields in that template. One of
+  the fields asks for a link to the ZEP, which you can leave blank until the ZEP
+  is filed. Then, go back and add the link.
+- [ ] **Make a copy of this template directory.**
+  Name it `NNNN-short-descriptive-title`, where `NNNN` is the issue number
+  (with no leading zeroes).
+- [ ] **Fill out as much of the zep.yaml file as you can.**
+  At minimum, complete the "Title", "Authors", "Status", and date-related fields.
+- [ ] **Fill out this file as best you can.**
+  Focus on the "Summary" and "Motivation" sections first. If you've already discussed
+  the idea with the Technical Steering Committee, this part should be easier.
+- [ ] **Create a PR for this ZEP.**
+  Assign it to members of the Technical Steering Committee who are sponsoring this process.
+- [ ] **Merge early and iterate.**
+  Don’t get bogged down in the details—focus on getting the goals clarified and the
+  ZEP merged quickly. You can fill in the specifics incrementally in later PRs.
+
+Just because a ZEP is merged doesn't mean it's complete or approved. Any ZEP marked
+as `provisional` is a working document and subject to change. You can mark unresolved
+sections like this:
+
+```
+<<[UNRESOLVED optional short context or usernames ]>>
+Stuff that is being argued.
+<<[/UNRESOLVED]>>
+```
+
+When editing ZEPs, aim for focused, single-topic PRs to keep discussions clear. If
+you disagree with a section, open a new PR with suggested changes.
+
+Each ZEP covers one "feature" or "enhancement" throughout its lifecycle. You don’t
+need a new ZEP for moving from beta to GA. If new details emerge, edit the existing
+ZEP. Once a feature is "implemented", major changes should go in new ZEPs.
+
+The latest instructions for this template can be found in [this repo](/NNNN-zep-template/README.md).
+
+**Note:** PRs to move a ZEP to `implementable`, or significant changes to an
+`implementable` ZEP, must be approved by all ZEP approvers. If an approver is no
+longer appropriate, updates to the list must be approved by the remaining approvers.
+-->
+
+# ZEP-NNNN: Your short, descriptive title
+
+<!--
+Keep the title short simple and descriptive. It should clearly convey what
+the ZEP is going to cover.
+-->
+
+<!--
+A table of contents helps reviewers quickly navigate the ZEP and highlights
+any additional information provided beyond the standard ZEP template.
+-->
+
+<!-- toc -->
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories (Optional)](#user-stories-optional)
+    - [Story 1](#story-1)
+    - [Story 2](#story-2)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+      - [Prerequisite testing updates](#prerequisite-testing-updates)
+      - [Unit tests](#unit-tests)
+      - [e2e tests](#e2e-tests)
+  - [Graduation Criteria](#graduation-criteria)
+  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+  - [Version Skew Strategy](#version-skew-strategy)
+- [Implementation History](#implementation-history)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
+<!-- /toc -->
+
+## Summary
+
+<!--
+This section is key for creating high-quality, user-focused documentation
+like release notes or a roadmap. You should gather this info before
+implementation starts to keep the focus on development, not writing. ZEP
+editors should ensure the `Summary` is clear and useful for a broad audience.
+
+A good summary should be at least a paragraph long.
+
+Follow the [documentation style guide] for this section and the rest of the ZEP.
+Keep line lengths reasonable to make it easier for reviewers to provide
+feedback and reduce unnecessary changes.
+
+[documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
+-->
+
+There are several fields in the ZarfPackageConfig v1alpha1 that can be restructured or removed to provide a better experience to creators of Zarf packages. 
+
+## Motivation
+
+<!--
+This section is for explicitly listing the motivation, goals, and non-goals of
+this ZEP.  Describe why the change is important and the benefits to users. You
+can also optionally include links to [experience reports], [community slacks],
+or other references to show the community's interest in the ZEP.
+
+[experience reports]: https://go.dev/wiki/ExperienceReports
+[openssf slack]: https://openssf.slack.com/archives/C07AKUMBDMJ
+[kubernetes slack]: https://kubernetes.slack.com/archives/C03B6BJAUJ3
+-->
+
+### Goals
+
+<!--
+List the specific goals of the ZEP. What is it trying to achieve? How will we
+know that this has succeeded?
+-->
+
+- Detail all schema changes in the ZarfPackageConfig from v1alpha1 to v1beta1.
+
+### Non-Goals
+
+<!--
+What is out of scope for this ZEP? Listing non-goals helps to focus discussion
+and make progress.
+-->
+
+- Discuss upgrade / downgrade strategy for users and packages. This is detailed in 0048-schema-upgrade-process
+
+## Proposal
+
+<!--
+This is where you explain the specifics of the proposal. Provide enough detail
+for reviewers to clearly understand what you're proposing, but avoid including
+too many specifics like API designs or implementation details. Focus on the
+desired outcome and how success will be measured. The "Design Details" section
+below is for the real nitty-gritty.
+-->
+
+
+
+### User Stories (Optional)
+
+<!--
+Detail the things that people will be able to do if this ZEP is implemented.
+Include as much detail as possible so that people can understand the "how" of
+the system. The goal here is to make this feel real for users without getting
+bogged down.
+-->
+
+#### Story 1
+
+#### Story 2
+
+### Risks and Mitigations
+
+<!--
+What are the risks of this proposal, and how do we mitigate? Think broadly.
+For example, consider both security and how this will impact the larger
+Zarf ecosystem.
+
+How will security be reviewed, and by whom?
+
+How will UX be reviewed, and by whom?
+-->
+
+## Design Details
+
+<!--
+This section should contain enough information that the specifics of your
+change are understandable. This may include API specs (though not always
+required) or even code snippets. If there's any ambiguity about HOW your
+proposal will be implemented, this is the place to discuss that.
+-->
+
+### Test Plan
+
+<!--
+**Note:** *Not required until targeted at a release.*
+The goal is to ensure that we don't accept proposals with inadequate testing.
+
+All code is expected to have adequate tests (eventually with coverage
+expectations). Please adhere to the [Zarf testing guidelines][testing-guidelines]
+when drafting this test plan.
+
+[testing-guidelines]: https://docs.zarf.dev/contribute/testing/
+-->
+
+[ ] I/we understand the owners of the involved components may require updates to
+existing tests to make this code solid enough prior to committing the changes necessary
+to implement this proposal.
+
+### Graduation Criteria
+
+<!--
+**Note:** *Not required until you're targeting a release.*
+
+Define what needs to happen for this feature to move from alpha to beta to GA
+(General Availability). Focus on key signals or criteria that show the feature
+is ready for each stage.
+
+Consider the following stages when setting graduation criteria:
+- Alpha: Feature is behind a feature flag, basic tests in place.
+- Beta: Gather feedback from users, complete core features, add more tests.
+- GA: Prove real-world usage, complete rigorous testing, gather feedback.
+
+In general, features should wait at least two releases between Beta and GA to
+allow time for feedback. For features moving to GA, include conformance tests
+to ensure stability and compatibility.
+
+#### Deprecation
+If this feature will eventually be deprecated, plan for it:
+- Announce deprecation and support policy.
+- Wait at least two versions before fully removing it.
+-->
+
+### Upgrade / Downgrade Strategy
+
+<!--
+If applicable, how will the component be upgraded and downgraded? Make sure
+this is in the test plan.
+
+Consider the following in developing an upgrade/downgrade strategy for this
+proposal:
+- What changes (in invocations, configurations, API use, etc.) is an existing
+  package definition or deployment required to make on upgrade, in order to
+  maintain previous behavior?
+- What changes (in invocations, configurations, API use, etc.) is an existing
+  package definition or deployment required to make on upgrade, in order to
+  make use of the proposal?
+-->
+
+### Version Skew Strategy
+
+<!--
+If applicable, how will the component handle version skew with other
+components? What are the guarantees? Make sure this is in the test plan.
+
+Consider the following in developing a version skew strategy for this
+proposal:
+- Does this proposal involve coordinating behavior between components?
+  - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
+-->
+
+## Implementation History
+
+<!--
+Major milestones in the lifecycle of a ZEP should be tracked in this section.
+Major milestones might include:
+- the `Summary` and `Motivation` sections being merged, signaling acceptance of the ZEP
+- the `Proposal` section being merged, signaling agreement on a proposed design
+- the date implementation started
+- the first Zarf release where an initial version of the ZEP was available
+- the version of Zarf where the ZEP graduated to general availability
+- when the ZEP was retired or superseded
+-->
+
+## Drawbacks
+
+<!--
+Why should this ZEP _not_ be implemented?
+-->
+
+## Alternatives
+
+<!--
+What other approaches did you consider, and why did you rule them out? These do
+not need to be as detailed as the proposal, but should include enough
+information to express the idea and why it was not acceptable.
+-->
+
+## Infrastructure Needed (Optional)
+
+<!--
+Use this section if you need things from the project. Examples include a new repo,
+cloud infrastructure for testing or GitHub details. Listing these here
+allows the process to get these resources to be started right away.
+-->
diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml
new file mode 100644
index 0000000..d982c61
--- /dev/null
+++ b/0051-v1beta1-schema/zep.yaml
@@ -0,0 +1,34 @@
+schema-version: 1.0.0
+
+title: ZEP Template
+zep-number: NNNN
+authors:
+  - "@jane.doe"
+status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
+creation-date: yyyy-mm-dd
+reviewers:
+  - TBD
+  - "@alice.doe"
+approvers:
+  - TBD
+  - "@oscar.doe"
+
+see-also:
+  - "/1234-we-heard-you-like-zeps"
+  - "/5678-everyone-gets-a-zep"
+replaces:
+  - "/3456-replaced-zep"
+
+# The target maturity stage in the current dev cycle for this ZEP.
+stage: alpha|beta|stable
+
+# The most recent milestone for which work toward delivery of this ZEP has been
+# done. This can be the current (upcoming) milestone, if it is being actively
+# worked on.
+latest-milestone: "v0.39"
+
+# The milestone at which this feature was, or is targeted to be, at each stage.
+milestone:
+  alpha: "v0.39"
+  beta: "v0.40"
+  stable: "v1.0"

From 64b60245ae70e336585c8a57bc5aab447c141894 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 10:08:18 -0400
Subject: [PATCH 002/131] WIP

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 82 +++++++++++++++++++++++++++--------
 1 file changed, 63 insertions(+), 19 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7074e9f..43a9c60 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -45,12 +45,7 @@ The latest instructions for this template can be found in [this repo](/NNNN-zep-
 longer appropriate, updates to the list must be approved by the remaining approvers.
 -->
 
-# ZEP-NNNN: Your short, descriptive title
-
-<!--
-Keep the title short simple and descriptive. It should clearly convey what
-the ZEP is going to cover.
--->
+# ZEP-0051: v1beta1 schema
 
 <!--
 A table of contents helps reviewers quickly navigate the ZEP and highlights
@@ -78,7 +73,6 @@ any additional information provided beyond the standard ZEP template.
 - [Implementation History](#implementation-history)
 - [Drawbacks](#drawbacks)
 - [Alternatives](#alternatives)
-- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
 <!-- /toc -->
 
 ## Summary
@@ -98,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-There are several fields in the ZarfPackageConfig v1alpha1 that can be restructured or removed to provide a better experience to creators of Zarf packages. 
+Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some field in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. 
 
 ## Motivation
 
@@ -120,7 +114,7 @@ List the specific goals of the ZEP. What is it trying to achieve? How will we
 know that this has succeeded?
 -->
 
-- Detail all schema changes in the ZarfPackageConfig from v1alpha1 to v1beta1.
+- Detail the schema changes in the ZarfPackageConfig from v1alpha1 to v1beta1.
 
 ### Non-Goals
 
@@ -129,7 +123,7 @@ What is out of scope for this ZEP? Listing non-goals helps to focus discussion
 and make progress.
 -->
 
-- Discuss upgrade / downgrade strategy for users and packages. This is detailed in 0048-schema-upgrade-process
+- Discuss how the codebase will change to handle a new schema version. This is detailed in 0048-schema-upgrade-process
 
 ## Proposal
 
@@ -141,7 +135,48 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
+The v1beta1 schema will remove or rename several fields.
+
+- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` -> will be removed. `zarf dev convert` will automatically add them as fields under `.metadata.annotations`.
+- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
+- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
+- `setVariable` will be removed. It can be automatically migrated to the existing field `setVariables`.  
+- `scripts` will be removed. It can be automatically migrated to the existing field `actions`. 
+- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
+- `yolo` will be renamed to `airgap`. `airgap` will default to true
+- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
+- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
+- `.component.[x].charts` will break off fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. 
+```yaml
+- name: podinfo-repo-new
+  helm:
+    url: https://stefanprodan.github.io/podinfo
+    name: podinfo # replaces repoName since it's only applicable for helm chart repositories
+    version: 6.4.0
+
+- name: podinfo-git-new
+  git:
+    url: https://stefanprodan.github.io/podinfo@6.4.0
+    path: charts/podinfo
+    # no version field, Zarf will use the version in the chart.yaml at that git tag
+
+- name: podinfo-oci-new
+  oci:
+    url: oci://ghcr.io/stefanprodan/charts/podinfo
+    version: 6.4.0 
+
+- name: podinfo-local-same
+  local:
+   path: chart
+  # no version field, use local chart.yaml version
+```
+- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantages of `.wait.cluster` are that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
+  - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
+- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
+- `.components.[x].charts.variables` will be removed. This is an alpha feature that is replaced by Zarf values.
 
+In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema.
 
 ### User Stories (Optional)
 
@@ -168,6 +203,10 @@ How will security be reviewed, and by whom?
 How will UX be reviewed, and by whom?
 -->
 
+The fields `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. 
+
+The alpha field `.components.[x].charts.variables` has seen significant adoption. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. 
+
 ## Design Details
 
 <!--
@@ -190,10 +229,14 @@ when drafting this test plan.
 [testing-guidelines]: https://docs.zarf.dev/contribute/testing/
 -->
 
-[ ] I/we understand the owners of the involved components may require updates to
+[X] I/we understand the owners of the involved components may require updates to
 existing tests to make this code solid enough prior to committing the changes necessary
 to implement this proposal.
 
+There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition.
+
+There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, the current v1alpha1
+
 ### Graduation Criteria
 
 <!--
@@ -218,6 +261,13 @@ If this feature will eventually be deprecated, plan for it:
 - Wait at least two versions before fully removing it.
 -->
 
+- Alpha: fields are subject to change or rename. No backwards compatibility guarantees.
+- Beta: Fields will not change in a way that is not fully backwards compatible.
+- GA: We've received feedback that all of are changes are an improvement. Examples and tests in Zarf shift to using the v1beta1 schema.
+
+Deprecation:
+- This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least a year.
+
 ### Upgrade / Downgrade Strategy
 
 <!--
@@ -234,6 +284,8 @@ proposal:
   make use of the proposal?
 -->
 
+
+
 ### Version Skew Strategy
 
 <!--
@@ -272,11 +324,3 @@ What other approaches did you consider, and why did you rule them out? These do
 not need to be as detailed as the proposal, but should include enough
 information to express the idea and why it was not acceptable.
 -->
-
-## Infrastructure Needed (Optional)
-
-<!--
-Use this section if you need things from the project. Examples include a new repo,
-cloud infrastructure for testing or GitHub details. Listing these here
-allows the process to get these resources to be started right away.
--->

From 1ae1fc307b2169e9a4c01a4365366dca1f089039 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 10:17:16 -0400
Subject: [PATCH 003/131] add user story

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 95 ++++++++++++++++++++++++++++++++++-
 1 file changed, 94 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 43a9c60..9ae6bd9 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -176,7 +176,7 @@ The v1beta1 schema will remove or rename several fields.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.variables` will be removed. This is an alpha feature that is replaced by Zarf values.
 
-In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema.
+In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
 ### User Stories (Optional)
 
@@ -189,8 +189,101 @@ bogged down.
 
 #### Story 1
 
+As a user of Helm charts in my package, I have the following existing `zarf.yaml`:
+
+```yaml
+kind: ZarfPackageConfig
+metadata:
+  name: helm-charts
+components:
+  - name: demo-helm-charts
+    required: true
+    charts:
+      - name: podinfo-local
+        version: 6.4.0
+        namespace: podinfo-from-local-chart
+        localPath: chart
+        valuesFiles:
+          - values.yaml
+
+      - name: podinfo-oci
+        version: 6.4.0
+        namespace: podinfo-from-oci
+        url: oci://ghcr.io/stefanprodan/charts/podinfo
+        valuesFiles:
+          - values.yaml
+
+      - name: podinfo-git
+        version: 6.4.0
+        namespace: podinfo-from-git
+        url: https://github.com/stefanprodan/podinfo.git
+        gitPath: charts/podinfo
+        valuesFiles:
+          - values.yaml
+
+      - name: podinfo-repo
+        version: 6.4.0
+        namespace: podinfo-from-repo
+        url: https://stefanprodan.github.io/podinfo
+        repoName: podinfo
+        releaseName: cool-release-name
+        valuesFiles:
+          - values.yaml
+```
+
+I want to upgrade to the v1beta1 schema so I run `zarf dev convert`, which produces:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfPackageConfig
+metadata:
+  name: helm-charts
+  description: Example showcasing multiple ways to deploy helm charts
+  version: 0.0.1
+
+components:
+  - name: demo-helm-charts
+    optional: false  # Changed from `required: true`
+    charts:
+      - name: podinfo-local
+        namespace: podinfo-from-local-chart
+        local:
+          path: chart  # Changed from `localPath`
+        # version field removed - uses version from local chart.yaml
+        valuesFiles:
+          - values.yaml
+      - name: podinfo-oci
+        namespace: podinfo-from-oci
+        oci:
+          url: oci://ghcr.io/stefanprodan/charts/podinfo
+          version: 6.4.0
+        valuesFiles:
+          - values.yaml
+
+      - name: podinfo-git
+        namespace: podinfo-from-git
+        git:
+          url: https://github.com/stefanprodan/podinfo.git@6.4.0
+          path: charts/podinfo  # Changed from `gitPath`
+        # version field removed - uses version from chart.yaml at git tag
+        valuesFiles:
+          - values.yaml
+
+      - name: podinfo-repo
+        namespace: podinfo-from-repo
+        helm:
+          url: https://stefanprodan.github.io/podinfo
+          name: podinfo  # Changed from `repoName`
+          version: 6.4.0
+        releaseName: cool-release-name
+        valuesFiles:
+          - values.yaml
+```
+
 #### Story 2
 
+
+
 ### Risks and Mitigations
 
 <!--

From d6967e24cecbd90a3bb15a7be413a60419bf3288 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 11:16:26 -0400
Subject: [PATCH 004/131] health checks example

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 62 +++++++++++++++++++++++++++++++++--
 1 file changed, 59 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 9ae6bd9..ca68419 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -173,10 +173,12 @@ The v1beta1 schema will remove or rename several fields.
 ```
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantages of `.wait.cluster` are that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
   - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
+  - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
-- `.components.[x].charts.variables` will be removed. This is an alpha feature that is replaced by Zarf values.
+- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
+- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of `actions.[onAny].after`.
 
-In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
 ### User Stories (Optional)
 
@@ -282,7 +284,61 @@ components:
 
 #### Story 2
 
+As a user of health checks in my package, I have the following `zarf.yaml` in v1alpha1:
 
+```yaml
+kind: ZarfPackageConfig
+metadata:
+  name: health-checks
+  description: Deploys a simple pod to test health checks
+
+components:
+  - name: health-checks
+    required: true
+    manifests:
+      - name: ready-pod
+        namespace: health-checks
+        noWait: true
+        files:
+          - ready-pod.yaml
+    healthChecks:
+      - name: ready-pod
+        namespace: health-checks
+        apiVersion: v1
+        kind: Pod
+```
+
+I want to move to the latest schema so I run `zarf dev convert`, which produces:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfPackageConfig
+metadata:
+  name: health-checks
+  description: Deploys a simple pod to test health checks
+
+components:
+  - name: health-checks
+    optional: false  # Changed from `required: true`
+    manifests:
+      - name: ready-pod
+        namespace: health-checks
+        wait: false  # Changed from `noWait: true`
+        files:
+          - ready-pod.yaml
+    actions:
+      onDeploy:
+        after:
+          - wait:
+              cluster:
+                kind: Pod
+                name: ready-pod
+                namespace: health-checks
+                apiVersion: v1
+                # condition is empty, so Kstatus will be used for readiness check
+```
+
+The `healthChecks` field has been removed and replaced with an `actions.onDeploy.after` wait action that uses Kstatus for health checking when no explicit condition is set.
 
 ### Risks and Mitigations
 
@@ -298,7 +354,7 @@ How will UX be reviewed, and by whom?
 
 The fields `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. 
 
-The alpha field `.components.[x].charts.variables` has seen significant adoption. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. 
+The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. 
 
 ## Design Details
 

From 9aa4a78a8681d9eba1cf4357d8906a9ba6f7321c Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 11:21:23 -0400
Subject: [PATCH 005/131] motivation

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index ca68419..861ebcd 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -107,6 +107,13 @@ or other references to show the community's interest in the ZEP.
 [kubernetes slack]: https://kubernetes.slack.com/archives/C03B6BJAUJ3
 -->
 
+There are several open issues requesting enhancements to the schema. The general theme of these changes is to make the ZarfPackageConfig schema more intuitive to use.
+- [Refactor charts definition in zarf.yaml #2245](https://github.com/zarf-dev/zarf/issues/2245)
+- [Breaking Change: make components required by default #2059](https://github.com/zarf-dev/zarf/issues/2059)
+- [Use kstatus as the engine behind zarf tools wait-for and .wait.cluster #4077](https://github.com/zarf-dev/zarf/issues/4077)
+
+Additionally, users often struggle to use data injections. Usually, they would be be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926).
+
 ### Goals
 
 <!--
@@ -123,7 +130,7 @@ What is out of scope for this ZEP? Listing non-goals helps to focus discussion
 and make progress.
 -->
 
-- Discuss how the codebase will change to handle a new schema version. This is detailed in 0048-schema-upgrade-process
+- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-upgrade-process](https://github.com/zarf-dev/proposals/pull/49)
 
 ## Proposal
 

From 38fd5ded3d99005380d805bb0c131cfa256e4bd7 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 11:28:45 -0400
Subject: [PATCH 006/131] fixes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 861ebcd..73629e2 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -149,9 +149,9 @@ The v1beta1 schema will remove or rename several fields.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
 - `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
 - `setVariable` will be removed. It can be automatically migrated to the existing field `setVariables`.  
-- `scripts` will be removed. It can be automatically migrated to the existing field `actions`. 
+- `.components.[x].scripts` will be removed. It can be automatically migrated to the existing field `.components.[x].actions`. 
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
-- `yolo` will be renamed to `airgap`. `airgap` will default to true
+- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
 - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
 - `.component.[x].charts` will break off fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. 

From 52f55f9b4328490fac9b0e53191fba475bb099c4 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 11:57:47 -0400
Subject: [PATCH 007/131] restructure

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 73629e2..491aba6 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,19 +142,17 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-The v1beta1 schema will remove or rename several fields.
+The v1beta1 schema will rename, restructure, and remove several fields.
+
+### Renamed fields
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
-- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` -> will be removed. `zarf dev convert` will automatically add them as fields under `.metadata.annotations`.
+- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
-- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
-- `setVariable` will be removed. It can be automatically migrated to the existing field `setVariables`.  
-- `.components.[x].scripts` will be removed. It can be automatically migrated to the existing field `.components.[x].actions`. 
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
-- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
 - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
-- `.component.[x].charts` will break off fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. 
+- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. 
 ```yaml
 - name: podinfo-repo-new
   helm:
@@ -178,12 +176,22 @@ The v1beta1 schema will remove or rename several fields.
    path: chart
   # no version field, use local chart.yaml version
 ```
-- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantages of `.wait.cluster` are that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
+
+### Removed fields with automated replacement
+
+- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list.
+- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`.
+- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
+- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
   - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
   - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
+
+### Removed fields without replacement.
+
+- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
-- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of `actions.[onAny].after`.
 
 In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 

From 8a7d3696451a75bcee48df3cfbb76aec331be1a5 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 11:58:09 -0400
Subject: [PATCH 008/131] restructure

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 36 +++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 491aba6..7d2d872 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -144,6 +144,24 @@ below is for the real nitty-gritty.
 
 The v1beta1 schema will rename, restructure, and remove several fields.
 
+### Removed fields without replacement.
+
+- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
+- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
+- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
+
+In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+
+### Removed fields with automated replacement
+
+- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list.
+- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`.
+- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
+- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
+  - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
+  - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
+
 ### Renamed fields
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
@@ -177,24 +195,6 @@ The v1beta1 schema will rename, restructure, and remove several fields.
   # no version field, use local chart.yaml version
 ```
 
-### Removed fields with automated replacement
-
-- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list.
-- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`.
-- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
-- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
-- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
-  - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
-  - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
-
-### Removed fields without replacement.
-
-- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
-- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
-- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
-
-In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
-
 ### User Stories (Optional)
 
 <!--

From 0dfd1c7e58df7fc5b9c94695b3d19b57f7dfa97e Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 12:04:41 -0400
Subject: [PATCH 009/131] restructure

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7d2d872..a900d51 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,20 +142,20 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
+In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+
 The v1beta1 schema will rename, restructure, and remove several fields.
 
 ### Removed fields without replacement.
 
-- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead.
+- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
 
-In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
-
 ### Removed fields with automated replacement
 
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list.
-- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`.
+- `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 

From ffb02a2451508675fa64c00ffca813c12a20f0fd Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 12:05:26 -0400
Subject: [PATCH 010/131] easier to read condition

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index a900d51..4e6fb2a 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,7 +142,7 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+Zarf will determine the schema of the package definition using the `apiVersion` flag. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
 The v1beta1 schema will rename, restructure, and remove several fields.
 

From 776d4d047b37f638cb39eb9526f34ef8a84bffee Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 12:07:13 -0400
Subject: [PATCH 011/131] spelling

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 4e6fb2a..6dec514 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -150,7 +150,7 @@ The v1beta1 schema will rename, restructure, and remove several fields.
 
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
-- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
+- `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
 
 ### Removed fields with automated replacement
 

From b4f1ebf191657e5007dcaad2f92cdea24d38e769 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 14:44:20 -0400
Subject: [PATCH 012/131] zarf chart changes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 95 +++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 14 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 6dec514..de243b4 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -146,7 +146,7 @@ Zarf will determine the schema of the package definition using the `apiVersion`
 
 The v1beta1 schema will rename, restructure, and remove several fields.
 
-### Removed fields without replacement.
+### Removed fields without replacement
 
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
@@ -161,16 +161,7 @@ The v1beta1 schema will rename, restructure, and remove several fields.
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
   - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
   - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
-
-### Renamed fields
-
-- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
-- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
-- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
-- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
-- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
-- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
-- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. 
+- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. 
 ```yaml
 - name: podinfo-repo-new
   helm:
@@ -193,7 +184,16 @@ The v1beta1 schema will rename, restructure, and remove several fields.
   local:
    path: chart
   # no version field, use local chart.yaml version
-```
+```  
+
+### Renamed fields
+
+- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
+- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
+- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
+- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
+- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
+- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
 
 ### User Stories (Optional)
 
@@ -353,7 +353,7 @@ components:
                 # condition is empty, so Kstatus will be used for readiness check
 ```
 
-The `healthChecks` field has been removed and replaced with an `actions.onDeploy.after` wait action that uses Kstatus for health checking when no explicit condition is set.
+a v1beta1 package that replaces the `healthChecks` entry with an `onDeploy.after.wait.cluster` entry.
 
 ### Risks and Mitigations
 
@@ -367,7 +367,7 @@ How will security be reviewed, and by whom?
 How will UX be reviewed, and by whom?
 -->
 
-The fields `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. 
+The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. 
 
 The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. 
 
@@ -380,6 +380,73 @@ required) or even code snippets. If there's any ambiguity about HOW your
 proposal will be implemented, this is the place to discuss that.
 -->
 
+### Zarf Chart Changes
+
+The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+
+During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to the URL. This is consistent with the current Zarf behavior. 
+
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely.
+
+```go
+// ZarfChart defines a helm chart to be deployed.
+type ZarfChart struct {
+	// The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo.
+	Name string `json:"name"`
+  // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1
+  version string
+	// The Helm repo where the chart is stored
+	Helm HelmRepoSource `json:"helm,omitempty"`
+	// The Git repo where the chart is stored
+	Git GitRepoSource `json:"git,omitempty"`
+	// The local path where the chart is stored
+	Local LocalRepoSource `json:"local,omitempty"`
+	// The OCI registry where the chart is stored
+	OCI OCISource `json:"oci,omitempty"`
+	// The namespace to deploy the chart to.
+	Namespace string `json:"namespace,omitempty"`
+	// The name of the Helm release to create (defaults to the Zarf name of the chart).
+	ReleaseName string `json:"releaseName,omitempty"`
+	// Whether to not wait for chart resources to be ready before continuing.
+	Wait *bool `json:"wait,omitempty"`
+	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
+	ValuesFiles []string `json:"valuesFiles,omitempty"`
+  // [alpha] List of values sources to their Helm override target
+	Values []ZarfChartValue `json:"values,omitempty"`
+}
+
+// HelmRepoSource represents a Helm chart stored in a Helm repository.
+type HelmRepoSource struct {
+	// The name of a chart within a Helm repository
+	RepoName string `json:"repoName,omitempty"`
+	// The URL of the chart repository where the helm chart is stored.
+	URL string `json:"url"`
+  // The version of the chart to deploy; for git-based charts this is also the tag of the git repo by default (when not using the '@' syntax for 'repos').
+	Version string `json:"version"`
+}
+
+// GitRepoSource represents a Helm chart stored in a Git repository.
+type GitRepoSource struct {
+	// The URL of the git repository where the helm chart is stored.
+	URL string `json:"url"`
+	// The sub directory to the chart within a git repo.
+	Path string `json:"path,omitempty"`
+}
+
+// LocalRepoSource represents a Helm chart stored locally.
+type LocalRepoSource struct {
+	// The path to a local chart's folder or .tgz archive.
+	Path string `json:"path"`
+}
+
+// OCISource represents a Helm chart stored in an OCI registry.
+type OCISource struct {
+	// The URL of the OCI registry where the helm chart is stored.
+	URL     string `json:"url"`
+	Version string `json:"version"`
+}
+```
+
 ### Test Plan
 
 <!--

From 50d6dbd422de11a0b15f77f046612af0f6643dd8 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 15:06:24 -0400
Subject: [PATCH 013/131] zarf chart

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 37 ++++++++---------------------------
 1 file changed, 8 insertions(+), 29 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index de243b4..af9055e 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -161,30 +161,7 @@ The v1beta1 schema will rename, restructure, and remove several fields.
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
   - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
   - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
-- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. 
-```yaml
-- name: podinfo-repo-new
-  helm:
-    url: https://stefanprodan.github.io/podinfo
-    name: podinfo # replaces repoName since it's only applicable for helm chart repositories
-    version: 6.4.0
-
-- name: podinfo-git-new
-  git:
-    url: https://stefanprodan.github.io/podinfo@6.4.0
-    path: charts/podinfo
-    # no version field, Zarf will use the version in the chart.yaml at that git tag
-
-- name: podinfo-oci-new
-  oci:
-    url: oci://ghcr.io/stefanprodan/charts/podinfo
-    version: 6.4.0 
-
-- name: podinfo-local-same
-  local:
-   path: chart
-  # no version field, use local chart.yaml version
-```  
+- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
 ### Renamed fields
 
@@ -380,13 +357,13 @@ required) or even code snippets. If there's any ambiguity about HOW your
 proposal will be implemented, this is the place to discuss that.
 -->
 
-### Zarf Chart Changes
+### Zarf Helm Chart Changes
 
 The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
-During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to the URL. This is consistent with the current Zarf behavior. 
+During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely.
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this applies to internal conversions of v1alpha1 packages so function signatures can be updated to use v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
@@ -494,7 +471,7 @@ If this feature will eventually be deprecated, plan for it:
 
 - Alpha: fields are subject to change or rename. No backwards compatibility guarantees.
 - Beta: Fields will not change in a way that is not fully backwards compatible.
-- GA: We've received feedback that all of are changes are an improvement. Examples and tests in Zarf shift to using the v1beta1 schema.
+- GA: We've received feedback from users and are confident improve the user experience. Examples and tests in Zarf shift to using the v1beta1 schema.
 
 Deprecation:
 - This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least a year.
@@ -515,7 +492,7 @@ proposal:
   make use of the proposal?
 -->
 
-
+Once the v1beta1 package schema is released, all functions in Zarf will be changed to use v1beta1 objects. 
 
 ### Version Skew Strategy
 
@@ -529,6 +506,8 @@ proposal:
   - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
 -->
 
+
+
 ## Implementation History
 
 <!--

From 52b2b78bc0dd040b50000f5aae58901529b94008 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 15:32:03 -0400
Subject: [PATCH 014/131] zarf chart

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index af9055e..b62635a 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -148,13 +148,17 @@ The v1beta1 schema will rename, restructure, and remove several fields.
 
 ### Removed fields without replacement
 
+These fields will error when `zarf dev convert` is run and recommend an alternative method to achieve the desired behavior. 
+
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
 - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
 
 ### Removed fields with automated replacement
 
-- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list.
+`zarf dev convert` will work with these fields. 
+
+- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions, will be migrated to the end of the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
@@ -165,6 +169,8 @@ The v1beta1 schema will rename, restructure, and remove several fields.
 
 ### Renamed fields
 
+`zarf dev convert` will work with these fields. 
+
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
 - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
@@ -474,7 +480,7 @@ If this feature will eventually be deprecated, plan for it:
 - GA: We've received feedback from users and are confident improve the user experience. Examples and tests in Zarf shift to using the v1beta1 schema.
 
 Deprecation:
-- This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least a year.
+- This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
 
 ### Upgrade / Downgrade Strategy
 
@@ -492,7 +498,7 @@ proposal:
   make use of the proposal?
 -->
 
-Once the v1beta1 package schema is released, all functions in Zarf will be changed to use v1beta1 objects. 
+This is discussed more in detail in ZEP-0048
 
 ### Version Skew Strategy
 

From e571b1e65097ac7528416fd562a0c5a02880b0b1 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 15:37:54 -0400
Subject: [PATCH 015/131] grammar

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 12 ++++++------
 0051-v1beta1-schema/zep.yaml  |  6 +++---
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index b62635a..c3b0687 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some field in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. 
+Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. 
 
 ## Motivation
 
@@ -112,7 +112,7 @@ There are several open issues requesting enhancements to the schema. The general
 - [Breaking Change: make components required by default #2059](https://github.com/zarf-dev/zarf/issues/2059)
 - [Use kstatus as the engine behind zarf tools wait-for and .wait.cluster #4077](https://github.com/zarf-dev/zarf/issues/4077)
 
-Additionally, users often struggle to use data injections. Usually, they would be be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926).
+Additionally, users often struggle to use data injections. Usually, they would be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926).
 
 ### Goals
 
@@ -158,7 +158,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 `zarf dev convert` will work with these fields. 
 
-- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions, will be migrated to the end of the `actions.[onAny].after` list.
+- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be migrated to the end of the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
@@ -173,7 +173,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
 - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
-- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false.
+- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since `required` defaults to false
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
 - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
@@ -350,7 +350,7 @@ How will security be reviewed, and by whom?
 How will UX be reviewed, and by whom?
 -->
 
-The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. 
+The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. 
 
 The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. 
 
@@ -477,7 +477,7 @@ If this feature will eventually be deprecated, plan for it:
 
 - Alpha: fields are subject to change or rename. No backwards compatibility guarantees.
 - Beta: Fields will not change in a way that is not fully backwards compatible.
-- GA: We've received feedback from users and are confident improve the user experience. Examples and tests in Zarf shift to using the v1beta1 schema.
+- GA: Users have provided feedback that the new schema improves the UX. Examples and tests in Zarf shift to using the v1beta1 schema.
 
 Deprecation:
 - This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml
index d982c61..817ab91 100644
--- a/0051-v1beta1-schema/zep.yaml
+++ b/0051-v1beta1-schema/zep.yaml
@@ -1,9 +1,9 @@
 schema-version: 1.0.0
 
-title: ZEP Template
-zep-number: NNNN
+title: v1beta1 schema
+zep-number: 0051
 authors:
-  - "@jane.doe"
+  - "@austinabro321"
 status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
 creation-date: yyyy-mm-dd
 reviewers:

From 38a1249908d2883a42485e6be7add9e893924069 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Oct 2025 15:42:47 -0400
Subject: [PATCH 016/131] grammar

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c3b0687..a1fcf9c 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. 
+Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf; these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. 
 
 ## Motivation
 
@@ -173,8 +173,8 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
 - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
-- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since `required` defaults to false
-- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts`
+- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. This is a change in behavior since `required` defaults to false.
+- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
 - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
 
@@ -336,8 +336,6 @@ components:
                 # condition is empty, so Kstatus will be used for readiness check
 ```
 
-a v1beta1 package that replaces the `healthChecks` entry with an `onDeploy.after.wait.cluster` entry.
-
 ### Risks and Mitigations
 
 <!--
@@ -449,7 +447,7 @@ to implement this proposal.
 
 There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition.
 
-There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, the current v1alpha1
+There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA existing tests will shift to use the v1beta1 schema.
 
 ### Graduation Criteria
 
@@ -498,7 +496,7 @@ proposal:
   make use of the proposal?
 -->
 
-This is discussed more in detail in ZEP-0048
+This is discussed in more detail in ZEP-0048.
 
 ### Version Skew Strategy
 

From f7ba8377fbd91813dc15b16afe16c94c9caa79fe Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 21 Oct 2025 08:08:13 -0400
Subject: [PATCH 017/131] upgrade / downgrade

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index a1fcf9c..66fa2d9 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -447,7 +447,7 @@ to implement this proposal.
 
 There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition.
 
-There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA existing tests will shift to use the v1beta1 schema.
+There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, existing tests will shift to use the v1beta1 schema.
 
 ### Graduation Criteria
 
@@ -496,7 +496,7 @@ proposal:
   make use of the proposal?
 -->
 
-This is discussed in more detail in ZEP-0048.
+See upgrade / downgrade strategy in ZEP-0048
 
 ### Version Skew Strategy
 
@@ -510,7 +510,7 @@ proposal:
   - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
 -->
 
-
+See version skew strategy in ZEP-0048
 
 ## Implementation History
 

From 345e9c8b4add5a1585933efee0b9a84f1c68412f Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 21 Oct 2025 08:45:40 -0400
Subject: [PATCH 018/131] ZEP 0048

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 66fa2d9..90ae094 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -496,7 +496,7 @@ proposal:
   make use of the proposal?
 -->
 
-See upgrade / downgrade strategy in ZEP-0048
+See ZEP-0048
 
 ### Version Skew Strategy
 

From 9764cefe89397b236b59d297273f51722c120f30 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 21 Oct 2025 09:48:40 -0400
Subject: [PATCH 019/131] proposal

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 10 ++++++----
 0051-v1beta1-schema/zep.yaml  | 25 ++++++++++---------------
 2 files changed, 16 insertions(+), 19 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 90ae094..e2913c8 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf; these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. 
+Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. 
 
 ## Motivation
 
@@ -163,7 +163,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
-  - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`.
+  - Since Kstatus requires API version, `apiVersion` will be added as a field to `.wait.cluster`.
   - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
@@ -350,7 +350,7 @@ How will UX be reviewed, and by whom?
 
 The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. 
 
-The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. 
+The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to it's replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. 
 
 ## Design Details
 
@@ -496,7 +496,7 @@ proposal:
   make use of the proposal?
 -->
 
-See ZEP-0048
+See proposal in ZEP-0048
 
 ### Version Skew Strategy
 
@@ -525,6 +525,8 @@ Major milestones might include:
 - when the ZEP was retired or superseded
 -->
 
+- 2025-10-21: Proposal submitted
+
 ## Drawbacks
 
 <!--
diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml
index 817ab91..9d6cccf 100644
--- a/0051-v1beta1-schema/zep.yaml
+++ b/0051-v1beta1-schema/zep.yaml
@@ -4,31 +4,26 @@ title: v1beta1 schema
 zep-number: 0051
 authors:
   - "@austinabro321"
-status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
-creation-date: yyyy-mm-dd
+status: provisional
+creation-date: 2025-10-21
 reviewers:
-  - TBD
-  - "@alice.doe"
+  - "@zarf-dev"
 approvers:
-  - TBD
-  - "@oscar.doe"
+  - "@zarf-dev"
 
 see-also:
-  - "/1234-we-heard-you-like-zeps"
-  - "/5678-everyone-gets-a-zep"
-replaces:
-  - "/3456-replaced-zep"
+  - "/0048-schema-upgrade-process"
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: alpha|beta|stable
+stage: alpha
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
 # worked on.
-latest-milestone: "v0.39"
+latest-milestone: ""
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
-  alpha: "v0.39"
-  beta: "v0.40"
-  stable: "v1.0"
+  alpha: "TBD"
+  beta: "TBD"
+  stable: "TBD""

From 6841fa3c36f3e10960680906cbcbc15cd01c4ae9 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 21 Oct 2025 10:03:25 -0400
Subject: [PATCH 020/131] small fixes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index e2913c8..8912d33 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -151,17 +151,17 @@ The v1beta1 schema will rename, restructure, and remove several fields.
 These fields will error when `zarf dev convert` is run and recommend an alternative method to achieve the desired behavior. 
 
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
-- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
+- `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
 
 ### Removed fields with automated replacement
 
-`zarf dev convert` will work with these fields. 
+`zarf dev convert` will automatically migrate these fields.
 
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be migrated to the end of the `actions.[onAny].after` list.
-- `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing field `.components[x].actions.[onAny].setVariables`.
-- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. 
-- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings.
+- `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
+- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. 
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
   - Since Kstatus requires API version, `apiVersion` will be added as a field to `.wait.cluster`.
   - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
@@ -169,14 +169,14 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 ### Renamed fields
 
-`zarf dev convert` will work with these fields. 
+`zarf dev convert` will automatically migrate these fields.
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
 - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
-- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. This is a change in behavior since `required` defaults to false.
+- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components now default to being required by default.
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
-- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries`
-- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
+- `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`
+- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to   `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
 
 ### User Stories (Optional)
 
@@ -365,9 +365,9 @@ proposal will be implemented, this is the place to discuss that.
 
 The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
-During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
+During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this applies to internal conversions of v1alpha1 packages so function signatures can be updated to use v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use  function signatures that container v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
 
 ```go
 // ZarfChart defines a helm chart to be deployed.

From c6cb3891392bcd008ac9a64cdcaeceb66774e735 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Oct 2025 09:31:16 -0400
Subject: [PATCH 021/131] v1beta1

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 8912d33..895b916 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -162,9 +162,9 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
+- `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
 - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
-  - Since Kstatus requires API version, `apiVersion` will be added as a field to `.wait.cluster`.
-  - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`.
+  - `.healthChecks` will be appended to the end of the `.components[x].actions.onDeploy.After.wait.cluster` list.
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
 ### Renamed fields

From dd5c98475f148a6df72965d809f828f5d2199595 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 23 Oct 2025 15:25:29 -0400
Subject: [PATCH 022/131] zarf tools wait-for

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 895b916..15f820a 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -163,8 +163,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
-- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. 
-  - `.healthChecks` will be appended to the end of the `.components[x].actions.onDeploy.After.wait.cluster` list.
+- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster` during conversions. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
 ### Renamed fields
@@ -428,6 +427,12 @@ type OCISource struct {
 }
 ```
 
+#### Zarf Tools wait-for Changes
+
+`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shell out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. 
+
+v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set, and will be able to optionally set `condition` as kstatus only checks for readiness. 
+
 ### Test Plan
 
 <!--
@@ -478,7 +483,7 @@ If this feature will eventually be deprecated, plan for it:
 - GA: Users have provided feedback that the new schema improves the UX. Examples and tests in Zarf shift to using the v1beta1 schema.
 
 Deprecation:
-- This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
+- This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
 
 ### Upgrade / Downgrade Strategy
 

From 6423279b926e54ef8a6209194587984b158064dc Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 23 Oct 2025 15:34:54 -0400
Subject: [PATCH 023/131] space

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 15f820a..c8b0dc5 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -114,7 +114,7 @@ There are several open issues requesting enhancements to the schema. The general
 
 Additionally, users often struggle to use data injections. Usually, they would be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926).
 
-### Goals
+### Goals1
 
 <!--
 List the specific goals of the ZEP. What is it trying to achieve? How will we
@@ -175,7 +175,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components now default to being required by default.
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`
-- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to   `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
+- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
 
 ### User Stories (Optional)
 

From a1f1f3a0fd5528877ff9e28cdfae23961bf76732 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 23 Oct 2025 15:45:51 -0400
Subject: [PATCH 024/131] cleanup

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c8b0dc5..a799475 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -107,14 +107,14 @@ or other references to show the community's interest in the ZEP.
 [kubernetes slack]: https://kubernetes.slack.com/archives/C03B6BJAUJ3
 -->
 
-There are several open issues requesting enhancements to the schema. The general theme of these changes is to make the ZarfPackageConfig schema more intuitive to use.
+There are several open issues requesting enhancements to the schema. The general theme of these changes is to make it easier to create Zarf packages.
 - [Refactor charts definition in zarf.yaml #2245](https://github.com/zarf-dev/zarf/issues/2245)
 - [Breaking Change: make components required by default #2059](https://github.com/zarf-dev/zarf/issues/2059)
 - [Use kstatus as the engine behind zarf tools wait-for and .wait.cluster #4077](https://github.com/zarf-dev/zarf/issues/4077)
 
 Additionally, users often struggle to use data injections. Usually, they would be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926).
 
-### Goals1
+### Goals
 
 <!--
 List the specific goals of the ZEP. What is it trying to achieve? How will we
@@ -142,9 +142,9 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the `apiVersion` flag. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+Zarf will determine the schema of the package definition using the top level `apiVersion` field. `apiVersion` already exists as a top level field in the Zarf package config schema. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
-The v1beta1 schema will rename, restructure, and remove several fields.
+The v1beta1 schema will remove, restructure, and rename several fields.
 
 ### Removed fields without replacement
 
@@ -158,12 +158,12 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 `zarf dev convert` will automatically migrate these fields.
 
-- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be migrated to the end of the `actions.[onAny].after` list.
+- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
-- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster` during conversions. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
+- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
 ### Renamed fields
@@ -362,11 +362,11 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use  function signatures that container v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use  function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
@@ -429,9 +429,9 @@ type OCISource struct {
 
 #### Zarf Tools wait-for Changes
 
-`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shell out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. 
+`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. 
 
-v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set, and will be able to optionally set `condition` as kstatus only checks for readiness. 
+v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set.
 
 ### Test Plan
 

From 0251e7ace085106b316fd4692ad898d853539344 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 24 Oct 2025 08:56:12 -0400
Subject: [PATCH 025/131] fix

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index a799475..c55d534 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. 
+Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. 
 
 ## Motivation
 

From 27e195fdf2930787bc5e7691779fa3f1df40659c Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 24 Oct 2025 09:04:21 -0400
Subject: [PATCH 026/131] clenaup flow

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c55d534..6a2c1a0 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. 
+Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the space to make these changes. 
 
 ## Motivation
 
@@ -142,11 +142,11 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the top level `apiVersion` field. `apiVersion` already exists as a top level field in the Zarf package config schema. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
-The v1beta1 schema will remove, restructure, and rename several fields.
+The v1beta1 schema will remove, replace, and rename several fields.
 
-### Removed fields without replacement
+### Removed Fields
 
 These fields will error when `zarf dev convert` is run and recommend an alternative method to achieve the desired behavior. 
 
@@ -154,7 +154,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
 
-### Removed fields with automated replacement
+### Replaced / Restructured Fields
 
 `zarf dev convert` will automatically migrate these fields.
 
@@ -163,10 +163,10 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
-- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
+- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
-### Renamed fields
+### Renamed Fields
 
 `zarf dev convert` will automatically migrate these fields.
 
@@ -362,11 +362,11 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use  function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
@@ -450,8 +450,6 @@ when drafting this test plan.
 existing tests to make this code solid enough prior to committing the changes necessary
 to implement this proposal.
 
-There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition.
-
 There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, existing tests will shift to use the v1beta1 schema.
 
 ### Graduation Criteria

From dffa7bd19d8b9a6bf3aface287aad6806d77f015 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 24 Oct 2025 09:10:05 -0400
Subject: [PATCH 027/131] improve grammar and flow

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 40 +++++++++++++++++------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 6a2c1a0..8c4bdc0 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the space to make these changes. 
+Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the opportunity to make these changes. 
 
 ## Motivation
 
@@ -142,13 +142,13 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
 The v1beta1 schema will remove, replace, and rename several fields.
 
 ### Removed Fields
 
-These fields will error when `zarf dev convert` is run and recommend an alternative method to achieve the desired behavior. 
+If a package has these fields defined then `zarf dev convert` will error with and print a recommendation for an alternative.
 
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
@@ -160,9 +160,9 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
-- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. 
+- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
-- `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
+- `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion, `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
@@ -170,12 +170,12 @@ These fields will error when `zarf dev convert` is run and recommend an alternat
 
 `zarf dev convert` will automatically migrate these fields.
 
-- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`
-- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true
-- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components now default to being required by default.
+- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
+- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true.
+- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
-- `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`
-- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration)
+- `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
+- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 
 ### User Stories (Optional)
 
@@ -230,7 +230,7 @@ components:
           - values.yaml
 ```
 
-I want to upgrade to the v1beta1 schema so I run `zarf dev convert`, which produces:
+I want to upgrade to the v1beta1 schema, so I run `zarf dev convert`, which produces:
 
 ```yaml
 apiVersion: v1beta1
@@ -305,7 +305,7 @@ components:
         kind: Pod
 ```
 
-I want to move to the latest schema so I run `zarf dev convert`, which produces:
+I want to move to the latest schema, so I run `zarf dev convert`, which produces:
 
 ```yaml
 apiVersion: v1beta1
@@ -349,7 +349,7 @@ How will UX be reviewed, and by whom?
 
 The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. 
 
-The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to it's replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. 
+The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to its replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. 
 
 ## Design Details
 
@@ -364,9 +364,9 @@ proposal will be implemented, this is the place to discuss that.
 
 The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
-During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
+During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
@@ -429,7 +429,7 @@ type OCISource struct {
 
 #### Zarf Tools wait-for Changes
 
-`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. 
+`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set and condition is empty, then kstatus will be used as `wait-for`'s engine. 
 
 v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set.
 
@@ -476,12 +476,12 @@ If this feature will eventually be deprecated, plan for it:
 - Wait at least two versions before fully removing it.
 -->
 
-- Alpha: fields are subject to change or rename. No backwards compatibility guarantees.
+- Alpha: Fields are subject to change or rename. No backwards compatibility guarantees.
 - Beta: Fields will not change in a way that is not fully backwards compatible.
 - GA: Users have provided feedback that the new schema improves the UX. Examples and tests in Zarf shift to using the v1beta1 schema.
 
 Deprecation:
-- This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
+- This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version is generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
 
 ### Upgrade / Downgrade Strategy
 
@@ -499,7 +499,7 @@ proposal:
   make use of the proposal?
 -->
 
-See proposal in ZEP-0048
+See proposal in ZEP-0048.
 
 ### Version Skew Strategy
 
@@ -513,7 +513,7 @@ proposal:
   - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
 -->
 
-See version skew strategy in ZEP-0048
+See version skew strategy in ZEP-0048.
 
 ## Implementation History
 

From 9e27b3b1ec60be5105f1444256ef886ac589bb92 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 24 Oct 2025 11:47:00 -0400
Subject: [PATCH 028/131] add that default is removed

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 8c4bdc0..cdc1928 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -150,9 +150,10 @@ The v1beta1 schema will remove, replace, and rename several fields.
 
 If a package has these fields defined then `zarf dev convert` will error with and print a recommendation for an alternative.
 
-- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.
+- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.     
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
+- `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
 
 ### Replaced / Restructured Fields
 
@@ -270,7 +271,7 @@ components:
 
       - name: podinfo-repo
         namespace: podinfo-from-repo
-        helm:
+        helmRepo:
           url: https://stefanprodan.github.io/podinfo
           name: podinfo  # Changed from `repoName`
           version: 6.4.0
@@ -362,7 +363,7 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helmRepo`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
@@ -376,7 +377,7 @@ type ZarfChart struct {
   // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1
   version string
 	// The Helm repo where the chart is stored
-	Helm HelmRepoSource `json:"helm,omitempty"`
+	HelmRepo HelmRepoSource `json:"helmRepo,omitempty"`
 	// The Git repo where the chart is stored
 	Git GitRepoSource `json:"git,omitempty"`
 	// The local path where the chart is stored

From 8772404265f456a3334956acec8798767923b48e Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 24 Oct 2025 11:50:06 -0400
Subject: [PATCH 029/131] package definition

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md |   2 +-
 0051-v1beta1-schema/zarf.yaml | 443 ++++++++++++++++++++++++++++++++++
 2 files changed, 444 insertions(+), 1 deletion(-)
 create mode 100644 0051-v1beta1-schema/zarf.yaml

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index cdc1928..02ba76a 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -144,7 +144,7 @@ below is for the real nitty-gritty.
 
 Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
 
-The v1beta1 schema will remove, replace, and rename several fields.
+The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key. 
 
 ### Removed Fields
 
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
new file mode 100644
index 0000000..474658e
--- /dev/null
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -0,0 +1,443 @@
+kind: ZarfPackageConfig
+apiVersion: v1beta1
+metadata:
+  name: everything-zarf-package
+  description: A zarf package with a non empty value for every key - this demonstrates the changes proposed by ZEP-0051
+  version: v1.0.0
+  uncompressed: false
+  architecture: amd64
+  airgap: true # changed from yolo
+  annotations: # All of these are v0 fields that will be deprecated in favor of a choose your own adventure label map
+    authors: cool-kidz
+    documentation: https://my-package-documentation.com
+    source: https://my-git-server/my-package
+    url: https://my-package-website.com
+    vendor: my-vendor
+    image: https://my-image-url-to-use-in-deprecated-zarf-ui
+    anyway-you-want-it: thats-the-way-you-need-it
+  allowNamespaceOverride: true
+build: # Everything here is created by Zarf not be users
+  terminal: my-computer
+  user: my-user
+  architecture: amd64
+  timestamp: 2021-09-01T00:00:00Z
+  version: v1.0.0
+  migrations:
+    - scripts-to-actions
+  versionRequirements:
+    - version: 0.65.0
+      reason: "the package structure of Helm charts changed"
+  registryOverrides:
+    gcr.io: my-gcr.com
+  differential: true
+  differentialPackageVersion: "v0.99.9"
+  differentialMissing:
+    - missing-component
+  flavor: cool-flavor
+  lastNonBreakingVersion: "v0.99.9"
+  aggregateChecksum: shasum # this is moved from .metadata
+values:
+  files:
+    - values.yaml
+  schema: values-schema.json
+components:
+- name: a-component
+  description: Zarf description
+  optional: false # Component is required (default behavior)
+  only:
+    localOS: darwin
+    cluster:
+      architecture: amd64
+      distros:
+      - ubuntu
+    flavor: a-flavor # this will only be used when there are multiple components
+  import:
+    name: other-component-name
+    path: ABCD # Only path or URL will be used, not both
+    url: oci://
+  manifests:
+  - name: manifest
+    namespace: manifest-ns
+    files:
+    - a-file.yaml
+    kustomizeAllowAnyDirectory: false
+    kustomizations:
+    - a-kustomization.yaml
+    wait: false
+    template: true # Enable go-template processing
+  charts:
+  - name: chart
+    namespace: chart-ns
+    releaseName: chart-release
+    wait: true
+    valuesFiles:
+    - values.yaml
+    values:
+    - sourcePath: ".app.name"
+      targetPath: ".appName"
+    schemaValidation: true
+    helmRepo: # Only one of helm, git, oci, url, or local is allowed
+      url: https://stefanprodan.github.io/podinfo
+      name: podinfo # replaces repoName since it's only applicable in this situation
+      version: 6.4.0
+    git:
+      url: https://stefanprodan.github.io/podinfo
+      path: charts/podinfo
+    oci:
+      url: oci://ghcr.io/stefanprodan/charts/podinfo
+      version: 6.4.0
+    local:
+      path: chart
+  files:
+  - source: source-file.txt
+    target: target-file.txt
+    shasum: shasum
+    executable: false
+    symlinks:
+    - /path/to/symlink
+    extractPath: /path/to/extract
+    template: false # Disable go-template processing for this file
+  images:
+  - podinfo@v1
+  repos:
+  - https://github.com/defenseunicorns/zarf
+  actions:
+    onCreate:
+      defaults:
+        mute: true
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+      before:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+      after:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+      onFailure:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+    onDeploy:
+      defaults:
+        mute: true
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+      before:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+      after:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+      onFailure:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+    onRemove:
+      defaults:
+        mute: true
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+      before:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+      after:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+      onFailure:
+      - mute: false
+        timeout: 1m
+        retries: 0
+        dir: dir
+        env:
+        - ENV_VAR=FOO
+        cmd: echo hello
+        shell:
+          darwin: sh
+          linux: sh
+          windows: powershell
+        setVariables:
+        - name: VAR
+          sensitive: false
+          autoIndent: true
+          pattern: ".+"
+          type: raw
+        setValues:
+          - key: .json
+        description: action-description
+        wait:
+          cluster: # Only one of cluster / network can be used
+            apiVersion: v1
+            kind: pod
+            name: my-pod
+            namespace: pod-ns
+            condition: ready
+          network:
+            protocol: http
+            address: github.com
+            code: 200
+constants:
+- name: CONSTANT
+  value: constant-value
+  description: constant-value
+  autoIndent: false
+  pattern: ".+"
+variables:
+- name: VAR
+  sensitive: false
+  autoIndent: true
+  pattern: ".+"
+  type: raw
+  description: var
+  default: whatever
+  prompt: false

From 265b8bace51b0cf3b967cb584ab806c358fdcb66 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 28 Oct 2025 09:16:46 -0400
Subject: [PATCH 030/131] update build

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/zarf.yaml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 474658e..6323b57 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -31,10 +31,7 @@ build: # Everything here is created by Zarf not be users
     gcr.io: my-gcr.com
   differential: true
   differentialPackageVersion: "v0.99.9"
-  differentialMissing:
-    - missing-component
   flavor: cool-flavor
-  lastNonBreakingVersion: "v0.99.9"
   aggregateChecksum: shasum # this is moved from .metadata
 values:
   files:

From 0883be9d7c9b7357cb190de9f6fb78bc18cf2d4b Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 4 Dec 2025 16:18:21 -0500
Subject: [PATCH 031/131] update acceptance criteria

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 +---
 0051-v1beta1-schema/zep.yaml  | 6 +++---
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 02ba76a..10c010f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -477,9 +477,7 @@ If this feature will eventually be deprecated, plan for it:
 - Wait at least two versions before fully removing it.
 -->
 
-- Alpha: Fields are subject to change or rename. No backwards compatibility guarantees.
-- Beta: Fields will not change in a way that is not fully backwards compatible.
-- GA: Users have provided feedback that the new schema improves the UX. Examples and tests in Zarf shift to using the v1beta1 schema.
+The v1beta1 schema will not have an alpha/beta/GA phase. Creating a package with the v1beta1 schema will initially be behind a feature flag for at least two releases after the v1beta1 schema is introduced. During this time, the v1beta1 schema may remove or rename fields. Once the feature flag is enabled by default, there will be no removed or renamed fields until the next schema version. 
 
 Deprecation:
 - This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version is generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml
index 9d6cccf..ff5b7fb 100644
--- a/0051-v1beta1-schema/zep.yaml
+++ b/0051-v1beta1-schema/zep.yaml
@@ -15,7 +15,7 @@ see-also:
   - "/0048-schema-upgrade-process"
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: alpha
+stage: beta
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
@@ -24,6 +24,6 @@ latest-milestone: ""
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
-  alpha: "TBD"
-  beta: "TBD"
+  alpha: "NA"
+  beta: "TBD  "
   stable: "TBD""

From d804a391ff669856872fe8e2ad1f81f9d3293bfe Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 4 Dec 2025 16:23:13 -0500
Subject: [PATCH 032/131] zarf dev upgrade schema

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 10c010f..c2eac81 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,34 +142,34 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev upgrade-schema`. 
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key. 
 
 ### Removed Fields
 
-If a package has these fields defined then `zarf dev convert` will error with and print a recommendation for an alternative.
+If a package has these fields defined then `zarf dev upgrade-schema` will error with and print a recommendation for an alternative.
 
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.     
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
-- `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`.
+- `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
 - `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
 
 ### Replaced / Restructured Fields
 
-`zarf dev convert` will automatically migrate these fields.
+`zarf dev upgrade-schema` will automatically migrate these fields.
 
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`. 
-- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings.
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion, `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
 ### Renamed Fields
 
-`zarf dev convert` will automatically migrate these fields.
+`zarf dev upgrade-schema` will automatically migrate these fields.
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
 - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true.
@@ -231,7 +231,7 @@ components:
           - values.yaml
 ```
 
-I want to upgrade to the v1beta1 schema, so I run `zarf dev convert`, which produces:
+I want to upgrade to the v1beta1 schema, so I run `zarf dev upgrade-schema`, which produces:
 
 ```yaml
 apiVersion: v1beta1
@@ -306,7 +306,7 @@ components:
         kind: Pod
 ```
 
-I want to move to the latest schema, so I run `zarf dev convert`, which produces:
+I want to move to the latest schema, so I run `zarf dev upgrade-schema`, which produces:
 
 ```yaml
 apiVersion: v1beta1
@@ -367,7 +367,7 @@ The ZarfChart object will be restructured to match the code block below. Exactly
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
 
 ```go
 // ZarfChart defines a helm chart to be deployed.

From 1fb4f30226c2faa3ea6fde248d664a590a762dcc Mon Sep 17 00:00:00 2001
From: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
Date: Thu, 4 Dec 2025 16:23:32 -0500
Subject: [PATCH 033/131] Apply suggestions from code review

Co-authored-by: Kit Patella <kit@jepsen.io>
Signed-off-by: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c2eac81..c5e095f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -498,7 +498,7 @@ proposal:
   make use of the proposal?
 -->
 
-See proposal in ZEP-0048.
+See proposal in [ZEP-0048](https://github.com/zarf-dev/proposals/issues/48).
 
 ### Version Skew Strategy
 
@@ -512,7 +512,7 @@ proposal:
   - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
 -->
 
-See version skew strategy in ZEP-0048.
+See version skew strategy in [ZEP-0048](https://github.com/zarf-dev/proposals/issues/48).
 
 ## Implementation History
 

From a4e1eef7eefa66fdbd1cea89b378304386ccedc1 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 8 Dec 2025 15:26:01 -0500
Subject: [PATCH 034/131] make apiversion required

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c2eac81..948fc4f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,7 +142,7 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev upgrade-schema`. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev upgrade-schema`. `apiVersion` will be a required field in v1beta1. 
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key. 
 

From cd17d45d706234dab77b60e65fbd98450aef45a2 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 10:28:23 -0500
Subject: [PATCH 035/131] introduce other system for package templating

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index f3ed9ba..da8253f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -146,7 +146,9 @@ Zarf will determine the schema of the package definition using the existing opti
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key. 
 
-### Removed Fields
+### Schema changes
+
+#### Removed Fields
 
 If a package has these fields defined then `zarf dev upgrade-schema` will error with and print a recommendation for an alternative.
 
@@ -155,7 +157,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
 - `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
 
-### Replaced / Restructured Fields
+#### Replaced / Restructured Fields
 
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
@@ -167,7 +169,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
-### Renamed Fields
+#### Renamed Fields
 
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
@@ -178,6 +180,20 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 
+### Package Templates
+
+The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf package template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.
+
+Remote components will be introduced as the spiritual successor to skeleton packages within v1beta1. If a remote component includes templates, users will be required to run `zarf package template` then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages today which are published before templating, and templated on create.  
+
+The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml` then fallback to a `zarf.gen.yaml`.  
+
+`zarf package template` would follow component imports, so running `zarf package template` on a package that has a `.import.path` pointing to a directory containing a `zarf.tpl.yaml` will template the file. Since zarf.yaml files can have custom names if `import.path` points to a file called `<name>.yaml.gen`, then `zarf package template` will look for a file called `<name>.tpl.yaml`. Each file will be templated separately, so if a user creates import paths using package templating, their import paths will be searched for `zarf.tpl.yaml` files with the above logic.
+
+Package templates will be required to have a value, otherwise the command will fail. 
+
+The deliminator for go templates during `zarf package template` will be `[[ ]]`. This will separate package templates from the standard go template deliminator `{{ }}` which are used during on deploy actions.
+
 ### User Stories (Optional)
 
 <!--

From 60a62f2e0edebffc9583484552f2633d703f1647 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 10:36:40 -0500
Subject: [PATCH 036/131] initial description for components

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index da8253f..e568ea2 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -180,6 +180,12 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 
+### Component Imports
+
+There will be a new Kind called ZarfComponentConfig to allow declaring a single component to be imported from other packages. It will have it's own schema, and this schema will be verified on create and publish. ZarfComponentConfigs would be introduced alongside the v1beta1 schema, and will be importable only from v1beta1 packages. Components from ZarfPackageConfigs will not be importable from v1beta1 packages. 
+
+ZarfComponentConfigs will be able to define their own values and valuesSchema. The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have no default name as zarf.yaml files do. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same flavor for two components, then they will receive an error.
+
 ### Package Templates
 
 The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf package template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.

From af97778bdcaf84ce789fe9121cff0abaa7c5fec8 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 14:37:53 -0500
Subject: [PATCH 037/131] remote components

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index e568ea2..766b648 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -186,12 +186,22 @@ There will be a new Kind called ZarfComponentConfig to allow declaring a single
 
 ZarfComponentConfigs will be able to define their own values and valuesSchema. The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have no default name as zarf.yaml files do. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same flavor for two components, then they will receive an error.
 
+The `.import.path` field will not accept directories, users will give the filepath to the ZarfComponentConfig file they'd like to import.
+
+The `zarf dev` commands that accepts a directory containing a `zarf.yaml`, lint, inspect, and find-images, will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
+
+#### Remote Components
+
+Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
+
+Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flag `--flavor` and `--all-variants`. When `--all-variants` is passed all components will be published regardless of their `.only` block. 
+
+If a remote component includes templates, users will be required to run `zarf package template` then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages today which are published before templating. See [Package Templates](#package-templates) for more details.
+
 ### Package Templates
 
 The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf package template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.
 
-Remote components will be introduced as the spiritual successor to skeleton packages within v1beta1. If a remote component includes templates, users will be required to run `zarf package template` then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages today which are published before templating, and templated on create.  
-
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml` then fallback to a `zarf.gen.yaml`.  
 
 `zarf package template` would follow component imports, so running `zarf package template` on a package that has a `.import.path` pointing to a directory containing a `zarf.tpl.yaml` will template the file. Since zarf.yaml files can have custom names if `import.path` points to a file called `<name>.yaml.gen`, then `zarf package template` will look for a file called `<name>.tpl.yaml`. Each file will be templated separately, so if a user creates import paths using package templating, their import paths will be searched for `zarf.tpl.yaml` files with the above logic.

From ee79166aa63760903b62648387b92080e34dd999 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 14:42:14 -0500
Subject: [PATCH 038/131] grammar

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 766b648..28b982f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -182,21 +182,21 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 ### Component Imports
 
-There will be a new Kind called ZarfComponentConfig to allow declaring a single component to be imported from other packages. It will have it's own schema, and this schema will be verified on create and publish. ZarfComponentConfigs would be introduced alongside the v1beta1 schema, and will be importable only from v1beta1 packages. Components from ZarfPackageConfigs will not be importable from v1beta1 packages. 
+There will be a new Kind called ZarfComponentConfig to allow declaring a single component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be introduced alongside the v1beta1 schema, and will be importable only from v1beta1 packages. Components from ZarfPackageConfigs will not be importable from v1beta1 packages. 
 
 ZarfComponentConfigs will be able to define their own values and valuesSchema. The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have no default name as zarf.yaml files do. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same flavor for two components, then they will receive an error.
 
-The `.import.path` field will not accept directories, users will give the filepath to the ZarfComponentConfig file they'd like to import.
+The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they'd like to import.
 
-The `zarf dev` commands that accepts a directory containing a `zarf.yaml`, lint, inspect, and find-images, will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
+The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint, inspect, and find-images, will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
 
 #### Remote Components
 
-Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
+Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flag `--flavor` and `--all-variants`. When `--all-variants` is passed all components will be published regardless of their `.only` block. 
+Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all components will be published regardless of their `.only` block. 
 
-If a remote component includes templates, users will be required to run `zarf package template` then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages today which are published before templating. See [Package Templates](#package-templates) for more details.
+If a remote component includes templates, users will be required to run `zarf package template` and then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages which are published before templating. See [Package Templates](#package-templates) for more details.
 
 ### Package Templates
 

From 0ecc3574cf1bdc55f3f518a87123c25f7a1e53eb Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 14:46:48 -0500
Subject: [PATCH 039/131] grammar fixes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 28b982f..78c1655 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -202,13 +202,13 @@ If a remote component includes templates, users will be required to run `zarf pa
 
 The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf package template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.
 
-The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml` then fallback to a `zarf.gen.yaml`.  
+The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.  
 
-`zarf package template` would follow component imports, so running `zarf package template` on a package that has a `.import.path` pointing to a directory containing a `zarf.tpl.yaml` will template the file. Since zarf.yaml files can have custom names if `import.path` points to a file called `<name>.yaml.gen`, then `zarf package template` will look for a file called `<name>.tpl.yaml`. Each file will be templated separately, so if a user creates import paths using package templating, their import paths will be searched for `zarf.tpl.yaml` files with the above logic.
+`zarf package template` will follow component imports, so running `zarf package template` on a package that has a `.import.path` pointing to a directory containing a `zarf.tpl.yaml` will template the file. Since zarf.yaml files can have custom names, if `import.path` points to a file called `<name>.gen.yaml`, then `zarf package template` will look for a file called `<name>.tpl.yaml`. Each file will be templated separately, so if a user creates import paths using package templating, their import paths will be searched for `zarf.tpl.yaml` files with the above logic.
 
-Package templates will be required to have a value, otherwise the command will fail. 
+Package templates will be required to have a value; otherwise the command will fail. 
 
-The deliminator for go templates during `zarf package template` will be `[[ ]]`. This will separate package templates from the standard go template deliminator `{{ }}` which are used during on deploy actions.
+The delimiter for Go templates during `zarf package template` will be `[[ ]]`. This will separate package templates from the standard gG template delimiter `{{ }}` which are used during on-deploy actions.
 
 ### User Stories (Optional)
 

From 427569f9fd3498940052c0152aaa05029cfdec1d Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 14:55:07 -0500
Subject: [PATCH 040/131] user story

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 68 +++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 78c1655..baead6e 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -368,6 +368,74 @@ components:
                 # condition is empty, so Kstatus will be used for readiness check
 ```
 
+#### Story 3
+
+As a package creator, I have a logging component that I maintain locally and want to use a monitoring component published by my team to an OCI registry. I combine both into a single v1beta1 package.
+
+First, I define my local logging component in `logging.yaml`:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfComponentConfig
+components:
+  - name: logging
+    charts:
+      - name: loki
+        namespace: logging
+        local:
+          path: loki-chart
+        valuesFiles:
+          - loki-values.yaml
+```
+
+My teammate has published a monitoring component to our registry. Its source file, `monitoring.yaml`, looked like this before publishing:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfComponentConfig
+components:
+  - name: monitoring
+    charts:
+      - name: kube-prometheus-stack
+        namespace: monitoring
+        helmRepo:
+          url: https://prometheus-community.github.io/helm-charts
+          name: kube-prometheus-stack
+          version: 60.0.0
+        valuesFiles:
+          - prometheus-values.yaml
+```
+
+They published it with:
+
+```bash
+zarf package publish component monitoring.yaml oci://ghcr.io/my-org/components
+```
+
+Now I create a v1beta1 package that imports both components -- the local one by file path and the remote one by URL:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfPackageConfig
+metadata:
+  name: observability
+  description: Combines logging and monitoring into a single package
+
+components:
+  - name: logging
+    import:
+      path: logging.yaml
+  - name: monitoring
+    import:
+      url: oci://ghcr.io/my-org/components/monitoring
+```
+
+I can then create my package as usual:
+
+```bash
+zarf package create
+```
+
 ### Risks and Mitigations
 
 <!--

From 585ba5176bb818b1d7642b96dc2d048cd261c668 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 15:12:53 -0500
Subject: [PATCH 041/131] update examples

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 69 ++++++++++++++++++++++++++++++++---
 1 file changed, 64 insertions(+), 5 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index baead6e..55cedef 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -377,9 +377,10 @@ First, I define my local logging component in `logging.yaml`:
 ```yaml
 apiVersion: v1beta1
 kind: ZarfComponentConfig
+metadata:
+  name: logging
 components:
-  - name: logging
-    charts:
+  - charts:
       - name: loki
         namespace: logging
         local:
@@ -393,9 +394,11 @@ My teammate has published a monitoring component to our registry. Its source fil
 ```yaml
 apiVersion: v1beta1
 kind: ZarfComponentConfig
+metadata:
+  name: monitoring
+  version: 1.0.0
 components:
-  - name: monitoring
-    charts:
+  - charts:
       - name: kube-prometheus-stack
         namespace: monitoring
         helmRepo:
@@ -427,7 +430,7 @@ components:
       path: logging.yaml
   - name: monitoring
     import:
-      url: oci://ghcr.io/my-org/components/monitoring
+      url: oci://ghcr.io/my-org/components/monitoring:1.0.0
 ```
 
 I can then create my package as usual:
@@ -436,6 +439,62 @@ I can then create my package as usual:
 zarf package create
 ```
 
+#### Story 4
+
+As a package creator, I want to template image references and metadata into my package at build time. I write a `zarf.tpl.yaml` that uses Go templates with the `[[ ]]` delimiter:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfPackageConfig
+metadata:
+  name: my-app
+  description: "my-app [[ .ENVIRONMENT ]]"
+
+components:
+  - name: my-app
+    charts:
+      - name: my-app
+        namespace: my-app
+        oci:
+          url: oci://ghcr.io/my-org/charts/my-app
+          version: 1.0.0
+    images:
+      - [[ .MY_IMAGE ]]
+```
+
+I generate a `zarf.gen.yaml` for a specific release:
+
+```bash
+zarf package template --set ENVIRONMENT=upstream --set ghcr.io/my-org/my-image:0.0.1
+```
+
+This produces `zarf.gen.yaml`:
+
+```yaml
+apiVersion: v1beta1
+kind: ZarfPackageConfig
+metadata:
+  name: my-app
+  description: "my-app upstream"
+
+components:
+  - name: my-app
+    charts:
+      - name: my-app
+        namespace: my-app
+        oci:
+          url: oci://ghcr.io/my-org/charts/my-app
+          version: 1.0.0
+    images:
+      - ghcr.io/my-org/my-app:v2.4.1
+```
+
+I can then create my package from the generated file:
+
+```bash
+zarf package create
+```
+
 ### Risks and Mitigations
 
 <!--

From 19c2aa98abef57d4d709cfbd0617e302a7b138e1 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 15:44:31 -0500
Subject: [PATCH 042/131] api version

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 70 +++--------------------------------
 0051-v1beta1-schema/zarf.yaml | 10 -----
 2 files changed, 6 insertions(+), 74 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 55cedef..0b3f730 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -156,6 +156,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
 - `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
+- `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580)
 
 #### Replaced / Restructured Fields
 
@@ -165,7 +166,6 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
-- `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion, `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. 
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
 
@@ -174,12 +174,16 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
-- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 
+
+### Behavior Changes
+
+There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. Currently when `.cluster.condition` is empty Zarf will wait until the resource exists. In the v1beta1 schema, Zarf will wait for the resource to be ready using kstatus readiness checks. 
+
 ### Component Imports
 
 There will be a new Kind called ZarfComponentConfig to allow declaring a single component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be introduced alongside the v1beta1 schema, and will be importable only from v1beta1 packages. Components from ZarfPackageConfigs will not be importable from v1beta1 packages. 
@@ -312,62 +316,6 @@ components:
           - values.yaml
 ```
 
-#### Story 2
-
-As a user of health checks in my package, I have the following `zarf.yaml` in v1alpha1:
-
-```yaml
-kind: ZarfPackageConfig
-metadata:
-  name: health-checks
-  description: Deploys a simple pod to test health checks
-
-components:
-  - name: health-checks
-    required: true
-    manifests:
-      - name: ready-pod
-        namespace: health-checks
-        noWait: true
-        files:
-          - ready-pod.yaml
-    healthChecks:
-      - name: ready-pod
-        namespace: health-checks
-        apiVersion: v1
-        kind: Pod
-```
-
-I want to move to the latest schema, so I run `zarf dev upgrade-schema`, which produces:
-
-```yaml
-apiVersion: v1beta1
-kind: ZarfPackageConfig
-metadata:
-  name: health-checks
-  description: Deploys a simple pod to test health checks
-
-components:
-  - name: health-checks
-    optional: false  # Changed from `required: true`
-    manifests:
-      - name: ready-pod
-        namespace: health-checks
-        wait: false  # Changed from `noWait: true`
-        files:
-          - ready-pod.yaml
-    actions:
-      onDeploy:
-        after:
-          - wait:
-              cluster:
-                kind: Pod
-                name: ready-pod
-                namespace: health-checks
-                apiVersion: v1
-                # condition is empty, so Kstatus will be used for readiness check
-```
-
 #### Story 3
 
 As a package creator, I have a logging component that I maintain locally and want to use a monitoring component published by my team to an OCI registry. I combine both into a single v1beta1 package.
@@ -587,12 +535,6 @@ type OCISource struct {
 }
 ```
 
-#### Zarf Tools wait-for Changes
-
-`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set and condition is empty, then kstatus will be used as `wait-for`'s engine. 
-
-v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set.
-
 ### Test Plan
 
 <!--
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 6323b57..446c690 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -6,7 +6,6 @@ metadata:
   version: v1.0.0
   uncompressed: false
   architecture: amd64
-  airgap: true # changed from yolo
   annotations: # All of these are v0 fields that will be deprecated in favor of a choose your own adventure label map
     authors: cool-kidz
     documentation: https://my-package-documentation.com
@@ -134,7 +133,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -166,7 +164,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -198,7 +195,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -242,7 +238,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -274,7 +269,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -306,7 +300,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -350,7 +343,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -382,7 +374,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns
@@ -414,7 +405,6 @@ components:
         description: action-description
         wait:
           cluster: # Only one of cluster / network can be used
-            apiVersion: v1
             kind: pod
             name: my-pod
             namespace: pod-ns

From 80056b3b94aeae451e758a222ee5e12a855a3904 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 15:45:53 -0500
Subject: [PATCH 043/131] behavior changes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 0b3f730..c52f255 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -182,7 +182,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 ### Behavior Changes
 
-There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. Currently when `.cluster.condition` is empty Zarf will wait until the resource exists. In the v1beta1 schema, Zarf will wait for the resource to be ready using kstatus readiness checks. 
+There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig when `.cluster.condition` is empty Zarf will wait until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty Zarf will wait for the resource to be ready using kstatus readiness checks. 
 
 ### Component Imports
 

From 2cc6631c5e157b26c18a9c7a88a1d8667001d425 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 6 Feb 2026 15:47:34 -0500
Subject: [PATCH 044/131] zarf component config

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c52f255..431f394 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -190,7 +190,7 @@ There will be a new Kind called ZarfComponentConfig to allow declaring a single
 
 ZarfComponentConfigs will be able to define their own values and valuesSchema. The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have no default name as zarf.yaml files do. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same flavor for two components, then they will receive an error.
 
-The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they'd like to import.
+The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they are importing.
 
 The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint, inspect, and find-images, will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
 

From ebbc9fe94ddb44873316758e86a5fe24ddc77d2f Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 12:09:56 -0500
Subject: [PATCH 045/131] grammar updates

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 431f394..59aaca0 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -184,11 +184,11 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig when `.cluster.condition` is empty Zarf will wait until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty Zarf will wait for the resource to be ready using kstatus readiness checks. 
 
-### Component Imports
+### ZarfComponentConfig
 
-There will be a new Kind called ZarfComponentConfig to allow declaring a single component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be introduced alongside the v1beta1 schema, and will be importable only from v1beta1 packages. Components from ZarfPackageConfigs will not be importable from v1beta1 packages. 
+The v1beta1 APIVersion will introduce a new `Kind` called alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a single component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages. 
 
-ZarfComponentConfigs will be able to define their own values and valuesSchema. The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have no default name as zarf.yaml files do. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same flavor for two components, then they will receive an error.
+The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs, or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same value for two components, then they will receive an error.
 
 The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they are importing.
 
@@ -200,19 +200,19 @@ Skeleton packages will be replaced by remote components. Instead of publishing a
 
 Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all components will be published regardless of their `.only` block. 
 
-If a remote component includes templates, users will be required to run `zarf package template` and then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages which are published before templating. See [Package Templates](#package-templates) for more details.
+If a remote component includes templates, users will be required to run `zarf dev template` and then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages which are published before templating. See [Package Templates](#package-templates) for more details.
 
 ### Package Templates
 
-The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf package template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.
+The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.  
 
-`zarf package template` will follow component imports, so running `zarf package template` on a package that has a `.import.path` pointing to a directory containing a `zarf.tpl.yaml` will template the file. Since zarf.yaml files can have custom names, if `import.path` points to a file called `<name>.gen.yaml`, then `zarf package template` will look for a file called `<name>.tpl.yaml`. Each file will be templated separately, so if a user creates import paths using package templating, their import paths will be searched for `zarf.tpl.yaml` files with the above logic.
+`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml` Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `.tpl.yaml` file and Zarf will template the given file.
 
 Package templates will be required to have a value; otherwise the command will fail. 
 
-The delimiter for Go templates during `zarf package template` will be `[[ ]]`. This will separate package templates from the standard gG template delimiter `{{ }}` which are used during on-deploy actions.
+The delimiter for Go templates during `zarf dev template` will be `[[ ]]`. This will separate package templates from the standard Go template delimiter `{{ }}` which are used during on-deploy actions.
 
 ### User Stories (Optional)
 

From 6af045e6b2b3a91a163c827a337a970bfc59cf46 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 12:49:47 -0500
Subject: [PATCH 046/131] grammar and minor adjustments

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 1 +
 0051-v1beta1-schema/zarf.yaml | 1 -
 2 files changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 59aaca0..6f13d3d 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -157,6 +157,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
 - `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
 - `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580)
+- `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig)
 
 #### Replaced / Restructured Fields
 
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 446c690..1ab9627 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -48,7 +48,6 @@ components:
       - ubuntu
     flavor: a-flavor # this will only be used when there are multiple components
   import:
-    name: other-component-name
     path: ABCD # Only path or URL will be used, not both
     url: oci://
   manifests:

From aee32712adc1c06f181e76adbdce1e1cfe41546f Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 14:17:57 -0500
Subject: [PATCH 047/131] add in schema for component config

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 67 +++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 6f13d3d..086f13d 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -536,6 +536,73 @@ type OCISource struct {
 }
 ```
 
+### Zarf Component Config Schema
+
+The schema for the Zarf component config will look like so:
+
+```go
+// ComponentConfig is the top-level structure of a Zarf component config file.
+type ComponentConfig struct {
+	// The API version of the component config.
+	APIVersion string `json:"apiVersion,omitempty," jsonschema:"enum=zarf.dev/v1beta1"`
+	// The kind of component config.
+	Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
+	// Component metadata.
+	Metadata ZarfComponentMetadata `json:"metadata"`
+	// List of components to deploy.
+	Components []ZarfComponent `json:"components"`
+	// Values imports Zarf values files for templating and overriding Helm values.
+	Values ZarfValues `json:"values,omitempty"`
+	// Zarf-generated publish data for the component config.
+	PublishData ComponentPublishData `json:"publishData,omitempty"`
+}
+
+// Component is a reduced component definition used in component configs.
+type Component struct {
+	// Filter when this component is included in package creation or deployment.
+	Only ZarfComponentOnlyTarget `json:"only,omitempty"`
+	// Import a component from another Zarf package.
+	Import ZarfComponentImport `json:"import,omitempty"`
+	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
+	Manifests []ZarfManifest `json:"manifests,omitempty"`
+	// Helm charts to install during package deploy.
+	Charts []ZarfChart `json:"charts,omitempty"`
+	// Files or folders to place on disk during package deployment.
+	Files []ZarfFile `json:"files,omitempty"`
+	// List of OCI images to include in the package.
+	Images []string `json:"images,omitempty"`
+	// List of Tar files of images to bring into the package.
+	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
+	// List of git repos to include in the package.
+	Repos []string `json:"repos,omitempty"`
+	// Custom commands to run at various stages of a package lifecycle.
+	Actions ZarfComponentActions `json:"actions,omitempty"`
+}
+
+// ZarfComponentMetadata holds metadata about a component config.
+type ZarfComponentMetadata struct {
+	// Name to identify this component config.
+	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
+	// Additional information about this component config.
+	Description string `json:"description,omitempty"`
+	// Generic string to track the component config version.
+	Version string `json:"version,omitempty"`
+	// Annotations contains arbitrary metadata about the component config.
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+
+// ComponentPublishData is written during publish to track details of the component config.
+type ComponentPublishData struct {
+	// The version of Zarf used to build this component config.
+	ZarfVersion string `json:"zarfVersion"`
+	// Any migrations that have been run on this component config.
+	Migrations []string `json:"migrations,omitempty"`
+	// Requirements for specific package operations.
+	VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"`
+}
+```
+
+
 ### Test Plan
 
 <!--

From 6c463e1dc56bab676dc5ad2ccd7875502589e9fc Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 14:29:12 -0500
Subject: [PATCH 048/131] fixes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 086f13d..f717b79 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -189,7 +189,7 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 The v1beta1 APIVersion will introduce a new `Kind` called alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a single component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages. 
 
-The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will have not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs, or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same value for two components, then they will receive an error.
+The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs, or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same value for two components, then they will receive an error.
 
 The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they are importing.
 
@@ -201,11 +201,11 @@ Skeleton packages will be replaced by remote components. Instead of publishing a
 
 Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all components will be published regardless of their `.only` block. 
 
-If a remote component includes templates, users will be required to run `zarf dev template` and then run `zarf package publish`. There will be no templating during create. This differs from Skeleton packages which are published before templating. See [Package Templates](#package-templates) for more details.
+Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for templating changes.
 
 ### Package Templates
 
-The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a file with defined go templates.
+The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values file to define templates.
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.  
 
@@ -396,14 +396,14 @@ As a package creator, I want to template image references and metadata into my p
 apiVersion: v1beta1
 kind: ZarfPackageConfig
 metadata:
-  name: my-app
-  description: "my-app [[ .ENVIRONMENT ]]"
+  name: app
+  description: "app [[ .ENVIRONMENT ]]"
 
 components:
-  - name: my-app
+  - name: app
     charts:
-      - name: my-app
-        namespace: my-app
+      - name: app
+        namespace: app
         oci:
           url: oci://ghcr.io/my-org/charts/my-app
           version: 1.0.0
@@ -414,7 +414,7 @@ components:
 I generate a `zarf.gen.yaml` for a specific release:
 
 ```bash
-zarf package template --set ENVIRONMENT=upstream --set ghcr.io/my-org/my-image:0.0.1
+zarf dev template --set ENVIRONMENT=personal --set MY_IMAGE=ghcr.io/my-org/my-image:0.0.1
 ```
 
 This produces `zarf.gen.yaml`:
@@ -435,7 +435,7 @@ components:
           url: oci://ghcr.io/my-org/charts/my-app
           version: 1.0.0
     images:
-      - ghcr.io/my-org/my-app:v2.4.1
+      - ghcr.io/my-org/my-image:0.0.1
 ```
 
 I can then create my package from the generated file:
@@ -550,7 +550,7 @@ type ComponentConfig struct {
 	// Component metadata.
 	Metadata ZarfComponentMetadata `json:"metadata"`
 	// List of components to deploy.
-	Components []ZarfComponent `json:"components"`
+	Components []Component `json:"components"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values ZarfValues `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.

From 3b0e4e14417a1acf8fe979c58453bde4753b622d Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 15:09:46 -0500
Subject: [PATCH 049/131] variants and components

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 59 ++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 26 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index f717b79..4ec5e87 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -187,9 +187,11 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 ### ZarfComponentConfig
 
-The v1beta1 APIVersion will introduce a new `Kind` called alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a single component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages. 
+The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema. The top level `.component` field will be a list to allow for the same component to be defined with different flavors, OSs, or architectures. If a user tries to define more than one component without specifying the `.only` key, or if the only key is the same value for two components, then they will receive an error.
+A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that applies in all contexts. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. different flavors, OSs, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. Setting both `component` and `variants` will produce a schema error.
+
+The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
 The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they are importing.
 
@@ -199,9 +201,9 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all components will be published regardless of their `.only` block. 
+Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block.
 
-Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for templating changes.
+Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
 
 ### Package Templates
 
@@ -328,14 +330,14 @@ apiVersion: v1beta1
 kind: ZarfComponentConfig
 metadata:
   name: logging
-components:
-  - charts:
-      - name: loki
-        namespace: logging
-        local:
-          path: loki-chart
-        valuesFiles:
-          - loki-values.yaml
+component:
+  charts:
+    - name: loki
+      namespace: logging
+      local:
+        path: loki-chart
+      valuesFiles:
+        - loki-values.yaml
 ```
 
 My teammate has published a monitoring component to our registry. Its source file, `monitoring.yaml`, looked like this before publishing:
@@ -346,16 +348,16 @@ kind: ZarfComponentConfig
 metadata:
   name: monitoring
   version: 1.0.0
-components:
-  - charts:
-      - name: kube-prometheus-stack
-        namespace: monitoring
-        helmRepo:
-          url: https://prometheus-community.github.io/helm-charts
-          name: kube-prometheus-stack
-          version: 60.0.0
-        valuesFiles:
-          - prometheus-values.yaml
+component:
+  charts:
+    - name: kube-prometheus-stack
+      namespace: monitoring
+      helmRepo:
+        url: https://prometheus-community.github.io/helm-charts
+        name: kube-prometheus-stack
+        version: 60.0.0
+      valuesFiles:
+        - prometheus-values.yaml
 ```
 
 They published it with:
@@ -544,13 +546,17 @@ The schema for the Zarf component config will look like so:
 // ComponentConfig is the top-level structure of a Zarf component config file.
 type ComponentConfig struct {
 	// The API version of the component config.
-	APIVersion string `json:"apiVersion,omitempty," jsonschema:"enum=zarf.dev/v1beta1"`
+	APIVersion string `json:"apiVersion,omitempty" jsonschema:"enum=zarf.dev/v1beta1"`
 	// The kind of component config.
 	Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
 	// Component metadata.
 	Metadata ZarfComponentMetadata `json:"metadata"`
-	// List of components to deploy.
-	Components []Component `json:"components"`
+  // Exactly one of Component or Variants must be set.
+	// A single component definition that applies in all contexts.
+	Component *Component `json:"component,omitempty"`
+	// A list of component variants, each with a distinct .only filter. Use this when the
+	// component has different definitions for different flavors, OSs, or architectures.
+	Variants []Component `json:"variants,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values ZarfValues `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.
@@ -560,8 +566,9 @@ type ComponentConfig struct {
 // Component is a reduced component definition used in component configs.
 type Component struct {
 	// Filter when this component is included in package creation or deployment.
+	// Required when used in the variants list.
 	Only ZarfComponentOnlyTarget `json:"only,omitempty"`
-	// Import a component from another Zarf package.
+	// Import a component from another Zarf component config.
 	Import ZarfComponentImport `json:"import,omitempty"`
 	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
 	Manifests []ZarfManifest `json:"manifests,omitempty"`

From 3342c86676076481add72a1199d919e3abff03a0 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 15:11:03 -0500
Subject: [PATCH 050/131] variants

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 4ec5e87..2f0c4d9 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -556,7 +556,7 @@ type ComponentConfig struct {
 	Component *Component `json:"component,omitempty"`
 	// A list of component variants, each with a distinct .only filter. Use this when the
 	// component has different definitions for different flavors, OSs, or architectures.
-	Variants []Component `json:"variants,omitempty"`
+	Variants []Variant `json:"variants,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values ZarfValues `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.
@@ -565,9 +565,6 @@ type ComponentConfig struct {
 
 // Component is a reduced component definition used in component configs.
 type Component struct {
-	// Filter when this component is included in package creation or deployment.
-	// Required when used in the variants list.
-	Only ZarfComponentOnlyTarget `json:"only,omitempty"`
 	// Import a component from another Zarf component config.
 	Import ZarfComponentImport `json:"import,omitempty"`
 	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
@@ -586,6 +583,13 @@ type Component struct {
 	Actions ZarfComponentActions `json:"actions,omitempty"`
 }
 
+// Variant is a component definition with a required filter for when it applies.
+type Variant struct {
+	Component
+	// Filter when this variant is included in package creation or deployment.
+	Only ZarfComponentOnlyTarget `json:"only"`
+}
+
 // ZarfComponentMetadata holds metadata about a component config.
 type ZarfComponentMetadata struct {
 	// Name to identify this component config.

From 92ccd17b00129c076d31a9b8d5b84ae1ffc72e58 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 15:24:53 -0500
Subject: [PATCH 051/131] update zarf.yaml representing schema

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/zarf.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 1ab9627..c0a9017 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -36,6 +36,8 @@ values:
   files:
     - values.yaml
   schema: values-schema.json
+documentation:
+  my-file: "file.md"  
 components:
 - name: a-component
   description: Zarf description
@@ -94,6 +96,10 @@ components:
     template: false # Disable go-template processing for this file
   images:
   - podinfo@v1
+  imageArchives:
+  - path: podinfo.tar
+    images:
+      - podinfo:local
   repos:
   - https://github.com/defenseunicorns/zarf
   actions:

From f5caea219e3afab7b54d5935f7339b62243ac037 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 15:25:34 -0500
Subject: [PATCH 052/131] update zarf.yaml representing schema

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/zarf.yaml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index c0a9017..d44edc8 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -29,8 +29,10 @@ build: # Everything here is created by Zarf not be users
   registryOverrides:
     gcr.io: my-gcr.com
   differential: true
-  differentialPackageVersion: "v0.99.9"
   flavor: cool-flavor
+  versionRequirements:
+  - version: v0.68.0
+    reason: This package contains image archives which will only be recognized on v0.68.0+  
   aggregateChecksum: shasum # this is moved from .metadata
 values:
   files:

From 8d174a54650e78ea0638566f4444d87aa563de53 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 15:42:59 -0500
Subject: [PATCH 053/131] cleanup

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 2f0c4d9..9d35874 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -189,7 +189,7 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that applies in all contexts. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. different flavors, OSs, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. Setting both `component` and `variants` will produce a schema error.
+A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that is always importable. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. flavors, OSs, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. View the schema of this object in [design details](#zarf-component-config-schema)
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
@@ -201,17 +201,17 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block.
+Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is specified instead, `--all-variants` will have no affect when true, but will not error. 
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
 
 ### Package Templates
 
-The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This functionality will be removed in the v1beta1 schema. To replace this functionality, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values file to define templates.
+The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This format will be replaced in the v1beta1 schema with go templating. Additionally, instead of templating on create, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values style file to define templates.
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.  
 
-`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml` Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `.tpl.yaml` file and Zarf will template the given file.
+`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml` Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
 
 Package templates will be required to have a value; otherwise the command will fail. 
 

From 88a25fc6a82183aaee053d4aa3f37df976508775 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 9 Feb 2026 15:46:41 -0500
Subject: [PATCH 054/131] fix

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 9d35874..e61d582 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -150,12 +150,12 @@ The v1beta1 schema will remove, replace, and rename several fields. View this [z
 
 #### Removed Fields
 
-If a package has these fields defined then `zarf dev upgrade-schema` will error with and print a recommendation for an alternative.
+If a package has these fields defined then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
 
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.     
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
-- `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
+- `.components.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
 - `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580)
 - `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig)
 
@@ -189,7 +189,7 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that is always importable. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. flavors, OSs, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. View the schema of this object in [design details](#zarf-component-config-schema)
+A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that is always importable. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. flavors, OSs, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. View the schema of this object in [design details](#zarf-component-config-schema).
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
@@ -201,13 +201,13 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is specified instead, `--all-variants` will have no affect when true, but will not error. 
+Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect. 
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
 
 ### Package Templates
 
-The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This format will be replaced in the v1beta1 schema with go templating. Additionally, instead of templating on create, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values style file to define templates.
+The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This format will be replaced in the v1beta1 schema with Go templating. Additionally, instead of templating on create, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values style file to define templates.
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.  
 
@@ -426,7 +426,7 @@ apiVersion: v1beta1
 kind: ZarfPackageConfig
 metadata:
   name: my-app
-  description: "my-app upstream"
+  description: "my-app personal"
 
 components:
   - name: my-app
@@ -631,7 +631,7 @@ when drafting this test plan.
 existing tests to make this code solid enough prior to committing the changes necessary
 to implement this proposal.
 
-There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, existing tests will shift to use the v1beta1 schema.
+There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema is nears GA, existing tests will shift to use the v1beta1 schema.
 
 ### Graduation Criteria
 

From f650866c869c0a5969e8c665bf290ce76372d932 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 12 Feb 2026 08:14:32 -0500
Subject: [PATCH 055/131] zarf features

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 45 +++++++++++++++++++++++++++++++++++
 0051-v1beta1-schema/zarf.yaml |  9 ++++++-
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index e61d582..28021fe 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -180,11 +180,34 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 
+### New Fields
+
+- `.components[x].features` will be introduced to avoid magic names in Init package components. See [Zarf Features](#zarf-features) for more details.
 
 ### Behavior Changes
 
+#### Wait Changes
+
 There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig when `.cluster.condition` is empty Zarf will wait until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty Zarf will wait for the resource to be ready using kstatus readiness checks. 
 
+#### Zarf Features
+
+In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain init logic. For instance, the injector is always run when an init component has a name "zarf-seed-registry". These magical names have caused confusion for custom init package creators [#4528](https://github.com/zarf-dev/zarf/issues/4528) and leave little room for configurability. 
+
+There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures that Features are only used in packages that are `Kind: ZarfInitConfig`. This validation will run after the import chain is resolved. 
+
+View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity given Zarf Features are the only difference.
+
+```yaml
+- name: zarf-seed-registry
+  features:
+    isRegistry: true
+    injector:
+      enabled: true
+      values:
+        tolerations: ".injector.tolerations"
+```
+
 ### ZarfComponentConfig
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
@@ -581,6 +604,8 @@ type Component struct {
 	Repos []string `json:"repos,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
 	Actions ZarfComponentActions `json:"actions,omitempty"`
+  // Features of the Zarf CLI 
+  Features ZarfComponentFeatures `json:features,omitempty"`
 }
 
 // Variant is a component definition with a required filter for when it applies.
@@ -613,6 +638,26 @@ type ComponentPublishData struct {
 }
 ```
 
+### Zarf Features Schema
+
+The schema for Zarf Features:
+
+```go
+type ZarfComponentFeatures struct {                                                                                                                             
+  IsRegistry bool       `json:"isRegistry,omitempty"`
+  Injector   *Injector  `json:"injector,omitempty"`
+  IsAgent    bool       `json:"isAgent,omitempty"`
+}                                                                                                                                                      
+                                                                                                                                                                  
+type Injector struct {
+  Enabled bool             `json:"enabled"`
+  Values  *InjectorValues  `json:"values,omitempty"`
+}
+
+type InjectorValues struct {
+  Tolerations string `json:"tolerations,omitempty"`
+}
+```
 
 ### Test Plan
 
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index d44edc8..62e0c4b 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -1,4 +1,4 @@
-kind: ZarfPackageConfig
+kind: ZarfInitConfig
 apiVersion: v1beta1
 metadata:
   name: everything-zarf-package
@@ -54,6 +54,13 @@ components:
   import:
     path: ABCD # Only path or URL will be used, not both
     url: oci://
+  features:
+    isRegistry: false
+    injector:
+      enabled: true
+      values:
+        tolerations: ".injector.tolerations"
+    isAgent: false
   manifests:
   - name: manifest
     namespace: manifest-ns

From defbc5d0ff86da9496ba97134ec7bfdde1ceffb3 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 12 Feb 2026 08:39:43 -0500
Subject: [PATCH 056/131] alternatives and drawbacks

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 28021fe..668577d 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -753,6 +753,7 @@ Major milestones might include:
 -->
 
 - 2025-10-21: Proposal submitted
+- 2025-02-12: 
 
 ## Drawbacks
 
@@ -760,6 +761,9 @@ Major milestones might include:
 Why should this ZEP _not_ be implemented?
 -->
 
+### Component Import Reworks
+Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this re-write should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.  
+
 ## Alternatives
 
 <!--
@@ -767,3 +771,7 @@ What other approaches did you consider, and why did you rule them out? These do
 not need to be as detailed as the proposal, but should include enough
 information to express the idea and why it was not acceptable.
 -->
+
+### Component Import Schema
+
+Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.only` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allows for builtin schema validation, requiring the `.only` key with `.variants[]` but not with `.component`. 
\ No newline at end of file

From 38908afe64232a67b758ccd051acf42f15ac8fc5 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 12 Feb 2026 08:40:42 -0500
Subject: [PATCH 057/131] update history

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 668577d..4109cee 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -753,7 +753,7 @@ Major milestones might include:
 -->
 
 - 2025-10-21: Proposal submitted
-- 2025-02-12: 
+- 2025-02-12: Introduce Zarf Component Config, package templating changes, and Zarf features
 
 ## Drawbacks
 

From 345ad5ffd0f60ac2e80a2286238440944646eeae Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 13 Feb 2026 15:36:24 -0500
Subject: [PATCH 058/131] changing to zarf component publish

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 4109cee..3fea46c 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -224,7 +224,7 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using a new sub-command `zarf package publish component <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect. 
+Remote components will be published using the new command `zarf component publish <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect. 
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
 
@@ -386,7 +386,7 @@ component:
 They published it with:
 
 ```bash
-zarf package publish component monitoring.yaml oci://ghcr.io/my-org/components
+zarf component publish monitoring.yaml oci://ghcr.io/my-org/components
 ```
 
 Now I create a v1beta1 package that imports both components -- the local one by file path and the remote one by URL:

From ea9467a0a83c13c55cc60bebfe6ba537a60518bf Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 18 Feb 2026 13:32:49 -0500
Subject: [PATCH 059/131] make images a list of objects

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 7 ++++---
 0051-v1beta1-schema/zarf.yaml | 3 ++-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 3fea46c..ce49805 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -169,6 +169,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
+- `.component.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pull images from the Docker Daemon.
 
 #### Renamed Fields
 
@@ -433,7 +434,7 @@ components:
           url: oci://ghcr.io/my-org/charts/my-app
           version: 1.0.0
     images:
-      - [[ .MY_IMAGE ]]
+      - name: [[ .MY_IMAGE ]]
 ```
 
 I generate a `zarf.gen.yaml` for a specific release:
@@ -460,7 +461,7 @@ components:
           url: oci://ghcr.io/my-org/charts/my-app
           version: 1.0.0
     images:
-      - ghcr.io/my-org/my-image:0.0.1
+      - name: ghcr.io/my-org/my-image:0.0.1
 ```
 
 I can then create my package from the generated file:
@@ -597,7 +598,7 @@ type Component struct {
 	// Files or folders to place on disk during package deployment.
 	Files []ZarfFile `json:"files,omitempty"`
 	// List of OCI images to include in the package.
-	Images []string `json:"images,omitempty"`
+	Images []ZarfImage `json:"images,omitempty"`
 	// List of Tar files of images to bring into the package.
 	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
 	// List of git repos to include in the package.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 62e0c4b..3b26030 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -104,7 +104,8 @@ components:
     extractPath: /path/to/extract
     template: false # Disable go-template processing for this file
   images:
-  - podinfo@v1
+    - name: - podinfo@v1
+      source: "registry" # optional - registry is the default value
   imageArchives:
   - path: podinfo.tar
     images:

From 3c09167c11314a4f26fad43e124e5ee521b25747 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 16 Mar 2026 10:45:08 -0400
Subject: [PATCH 060/131] keep default

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index ce49805..da7f3ea 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -155,7 +155,6 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.     
 - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
-- `.components.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. 
 - `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580)
 - `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig)
 

From 5281d1033c9f4300c10a8af348bea505851aefc6 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 12:03:50 -0400
Subject: [PATCH 061/131] update to reference 0048 on disk

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index da7f3ea..1e5d996 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -702,7 +702,7 @@ If this feature will eventually be deprecated, plan for it:
 - Wait at least two versions before fully removing it.
 -->
 
-The v1beta1 schema will not have an alpha/beta/GA phase. Creating a package with the v1beta1 schema will initially be behind a feature flag for at least two releases after the v1beta1 schema is introduced. During this time, the v1beta1 schema may remove or rename fields. Once the feature flag is enabled by default, there will be no removed or renamed fields until the next schema version. 
+The v1beta1 schema will not have an alpha/beta/GA phase. It will follow the graduation criteria laid out by [0048-schema-update-process](../0048-schema-update-process/README.md#graduation-criteria).
 
 Deprecation:
 - This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version is generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
@@ -723,7 +723,7 @@ proposal:
   make use of the proposal?
 -->
 
-See proposal in [ZEP-0048](https://github.com/zarf-dev/proposals/issues/48).
+See the proposal section in [0048-schema-update-process](../0048-schema-update-process/README.md#proposal)
 
 ### Version Skew Strategy
 
@@ -737,7 +737,7 @@ proposal:
   - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
 -->
 
-See version skew strategy in [ZEP-0048](https://github.com/zarf-dev/proposals/issues/48).
+See the version skew strategy in  [0048-schema-update-process](../0048-schema-update-process/README.md#version-skew-strategy)
 
 ## Implementation History
 

From f4d602b9515187607017a1e1755ac08eaf528f2a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 12:10:34 -0400
Subject: [PATCH 062/131] grammar and zep fixes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0048-schema-update-process/zep.yaml |  8 ++--
 0051-v1beta1-schema/README.md       | 72 ++++++++++++++---------------
 0051-v1beta1-schema/zep.yaml        |  6 +--
 3 files changed, 42 insertions(+), 44 deletions(-)

diff --git a/0048-schema-update-process/zep.yaml b/0048-schema-update-process/zep.yaml
index c7a5052..a2abf05 100644
--- a/0048-schema-update-process/zep.yaml
+++ b/0048-schema-update-process/zep.yaml
@@ -16,15 +16,13 @@ see-also:
 replaces:
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: alpha
+stage: ga
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
 # worked on.
-latest-milestone: "v0.65.0"
+latest-milestone: "v0.74.2"
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
-  alpha: "v0.65.0"
-  beta: "v0.65.0"
-  stable: "v0.65.0"
+  stable: "v0.74.2"
diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 1e5d996..7e530a4 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the opportunity to make these changes. 
+Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the opportunity to make these changes.
 
 ## Motivation
 
@@ -130,7 +130,7 @@ What is out of scope for this ZEP? Listing non-goals helps to focus discussion
 and make progress.
 -->
 
-- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-upgrade-process](https://github.com/zarf-dev/proposals/pull/49)
+- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-update-process](https://github.com/zarf-dev/proposals/pull/49)
 
 ## Proposal
 
@@ -142,9 +142,9 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev upgrade-schema`. `apiVersion` will be a required field in v1beta1. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev upgrade-schema`. `apiVersion` will be a required field in v1beta1.
 
-The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key. 
+The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key.
 
 ### Schema changes
 
@@ -152,11 +152,11 @@ The v1beta1 schema will remove, replace, and rename several fields. View this [z
 
 If a package has these fields defined then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
 
-- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead.     
-- `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). 
+- `.components.[x].group` will be removed. Users should use `components[x].only.flavor` instead.
+- `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926).
 - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
-- `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580)
-- `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig)
+- `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
+- `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig).
 
 #### Replaced / Restructured Fields
 
@@ -164,11 +164,11 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
-- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`. 
+- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
-- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes)
-- `.component.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pull images from the Docker Daemon.
+- `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
+- `.components.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon.
 
 #### Renamed Fields
 
@@ -188,13 +188,13 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 #### Wait Changes
 
-There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig when `.cluster.condition` is empty Zarf will wait until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty Zarf will wait for the resource to be ready using kstatus readiness checks. 
+There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf will wait until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks.
 
 #### Zarf Features
 
-In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain init logic. For instance, the injector is always run when an init component has a name "zarf-seed-registry". These magical names have caused confusion for custom init package creators [#4528](https://github.com/zarf-dev/zarf/issues/4528) and leave little room for configurability. 
+In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain init logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators [#4528](https://github.com/zarf-dev/zarf/issues/4528) and leave little room for configurability.
 
-There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures that Features are only used in packages that are `Kind: ZarfInitConfig`. This validation will run after the import chain is resolved. 
+There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures that Features are only used in packages that are `Kind: ZarfInitConfig`. This validation will run after the import chain is resolved.
 
 View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity given Zarf Features are the only difference.
 
@@ -224,19 +224,19 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using the new command `zarf component publish <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect. 
+Remote components will be published using the new command `zarf component publish <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
 
 ### Package Templates
 
-The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This format will be replaced in the v1beta1 schema with Go templating. Additionally, instead of templating on create, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values style file to define templates.
+The Zarf v1alpha1 schema allows for package templates during create using the ###ZARF_PKG_TMPL_*### format. This format will be replaced in the v1beta1 schema with Go templating. Additionally, instead of templating on create, a new command `zarf dev template` will be introduced. This command will take in a zarf.tpl.yaml file, and will output a zarf.gen.yaml file based on the Go templating result. The command will accept a flag `--set` to set templates and a flag `--set-file` which will accept a values style file to define templates.
 
-The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.  
+The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.
 
 `zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml` Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
 
-Package templates will be required to have a value; otherwise the command will fail. 
+Package templates will be required to have a value; otherwise the command will fail.
 
 The delimiter for Go templates during `zarf dev template` will be `[[ ]]`. This will separate package templates from the standard Go template delimiter `{{ }}` which are used during on-deploy actions.
 
@@ -342,7 +342,7 @@ components:
           - values.yaml
 ```
 
-#### Story 3
+#### Story 2
 
 As a package creator, I have a logging component that I maintain locally and want to use a monitoring component published by my team to an OCI registry. I combine both into a single v1beta1 package.
 
@@ -413,7 +413,7 @@ I can then create my package as usual:
 zarf package create
 ```
 
-#### Story 4
+#### Story 3
 
 As a package creator, I want to template image references and metadata into my package at build time. I write a `zarf.tpl.yaml` that uses Go templates with the `[[ ]]` delimiter:
 
@@ -481,9 +481,9 @@ How will security be reviewed, and by whom?
 How will UX be reviewed, and by whom?
 -->
 
-The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. 
+The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result.
 
-The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to its replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. 
+The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to its replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables.
 
 ## Design Details
 
@@ -498,9 +498,9 @@ proposal will be implemented, this is the place to discuss that.
 
 The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helmRepo`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
-During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. 
+During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior.
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top level `version` field to the right sub object, or drop it when not applicable. 
+Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top level `version` field to the right sub object, or drop it when not applicable.
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
@@ -543,7 +543,7 @@ type HelmRepoSource struct {
 type GitRepoSource struct {
 	// The URL of the git repository where the helm chart is stored.
 	URL string `json:"url"`
-	// The sub directory to the chart within a git repo.
+	// The subdirectory to the chart within a git repo.
 	Path string `json:"path,omitempty"`
 }
 
@@ -604,8 +604,8 @@ type Component struct {
 	Repos []string `json:"repos,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
 	Actions ZarfComponentActions `json:"actions,omitempty"`
-  // Features of the Zarf CLI 
-  Features ZarfComponentFeatures `json:features,omitempty"`
+  // Features of the Zarf CLI
+  Features ZarfComponentFeatures `json:"features,omitempty"`
 }
 
 // Variant is a component definition with a required filter for when it applies.
@@ -643,12 +643,12 @@ type ComponentPublishData struct {
 The schema for Zarf Features:
 
 ```go
-type ZarfComponentFeatures struct {                                                                                                                             
+type ZarfComponentFeatures struct {
   IsRegistry bool       `json:"isRegistry,omitempty"`
   Injector   *Injector  `json:"injector,omitempty"`
   IsAgent    bool       `json:"isAgent,omitempty"`
-}                                                                                                                                                      
-                                                                                                                                                                  
+}
+
 type Injector struct {
   Enabled bool             `json:"enabled"`
   Values  *InjectorValues  `json:"values,omitempty"`
@@ -676,7 +676,7 @@ when drafting this test plan.
 existing tests to make this code solid enough prior to committing the changes necessary
 to implement this proposal.
 
-There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema is nears GA, existing tests will shift to use the v1beta1 schema.
+There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears GA, existing tests will shift to use the v1beta1 schema.
 
 ### Graduation Criteria
 
@@ -723,7 +723,7 @@ proposal:
   make use of the proposal?
 -->
 
-See the proposal section in [0048-schema-update-process](../0048-schema-update-process/README.md#proposal)
+See the proposal section in [0048-schema-update-process](../0048-schema-update-process/README.md#proposal).
 
 ### Version Skew Strategy
 
@@ -737,7 +737,7 @@ proposal:
   - (i.e. the Zarf Agent and CLI? The init package and the CLI?)
 -->
 
-See the version skew strategy in  [0048-schema-update-process](../0048-schema-update-process/README.md#version-skew-strategy)
+See the version skew strategy in [0048-schema-update-process](../0048-schema-update-process/README.md#version-skew-strategy).
 
 ## Implementation History
 
@@ -753,7 +753,7 @@ Major milestones might include:
 -->
 
 - 2025-10-21: Proposal submitted
-- 2025-02-12: Introduce Zarf Component Config, package templating changes, and Zarf features
+- 2026-02-12: Introduced Zarf Component Config, package templating changes, and Zarf features
 
 ## Drawbacks
 
@@ -762,7 +762,7 @@ Why should this ZEP _not_ be implemented?
 -->
 
 ### Component Import Reworks
-Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this re-write should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.  
+Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this re-write should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
 ## Alternatives
 
@@ -774,4 +774,4 @@ information to express the idea and why it was not acceptable.
 
 ### Component Import Schema
 
-Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.only` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allows for builtin schema validation, requiring the `.only` key with `.variants[]` but not with `.component`. 
\ No newline at end of file
+Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.only` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allows for builtin schema validation, requiring the `.only` key with `.variants[]` but not with `.component`.
\ No newline at end of file
diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml
index ff5b7fb..458cf8a 100644
--- a/0051-v1beta1-schema/zep.yaml
+++ b/0051-v1beta1-schema/zep.yaml
@@ -4,7 +4,7 @@ title: v1beta1 schema
 zep-number: 0051
 authors:
   - "@austinabro321"
-status: provisional
+status: implementable
 creation-date: 2025-10-21
 reviewers:
   - "@zarf-dev"
@@ -15,7 +15,7 @@ see-also:
   - "/0048-schema-upgrade-process"
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: beta
+stage: ga
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
@@ -25,5 +25,5 @@ latest-milestone: ""
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
   alpha: "NA"
-  beta: "TBD  "
+  beta: "TBD"
   stable: "TBD""

From 89773d5f857f69b10b85be7fda7ab39a6e7d437f Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 12:20:19 -0400
Subject: [PATCH 063/131] grammar

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 56 +++++++++++++++++------------------
 1 file changed, 28 insertions(+), 28 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7e530a4..218409a 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -130,7 +130,7 @@ What is out of scope for this ZEP? Listing non-goals helps to focus discussion
 and make progress.
 -->
 
-- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-update-process](https://github.com/zarf-dev/proposals/pull/49)
+- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-update-process](https://github.com/zarf-dev/proposals/pull/49).
 
 ## Proposal
 
@@ -165,8 +165,8 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
-- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
-- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
+- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
 - `.components.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon.
 
@@ -194,9 +194,9 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain init logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators [#4528](https://github.com/zarf-dev/zarf/issues/4528) and leave little room for configurability.
 
-There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures that Features are only used in packages that are `Kind: ZarfInitConfig`. This validation will run after the import chain is resolved.
+There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures Features are only used in packages that are `Kind: ZarfInitConfig`. This validation will run after the import chain is resolved.
 
-View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity given Zarf Features are the only difference.
+View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity, given Zarf Features are the only difference.
 
 ```yaml
 - name: zarf-seed-registry
@@ -210,15 +210,15 @@ View the full schema in [Zarf Features Schema](#zarf-features-schema). There wil
 
 ### ZarfComponentConfig
 
-The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only from v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
+The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only by v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that is always importable. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. flavors, OSs, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. View the schema of this object in [design details](#zarf-component-config-schema).
+A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that is always importable. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. flavors, OSes, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. View the schema of this object in [design details](#zarf-component-config-schema).
 
-The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and help encourage a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
+The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
-The `.import.path` field will not accept directories; users will give the filepath to the ZarfComponentConfig file they are importing.
+The `.import.path` field will not accept directories; users will give the file path to the ZarfComponentConfig file they are importing.
 
-The `zarf dev` commands that accept a directory containing a `zarf.yaml`, lint, inspect, and find-images, will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
+The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint, inspect, and find-images) will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
 
 #### Remote Components
 
@@ -234,11 +234,11 @@ The Zarf v1alpha1 schema allows for package templates during create using the ##
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.
 
-`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml` Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
+`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml`, Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
 
 Package templates will be required to have a value; otherwise the command will fail.
 
-The delimiter for Go templates during `zarf dev template` will be `[[ ]]`. This will separate package templates from the standard Go template delimiter `{{ }}` which are used during on-deploy actions.
+The delimiter for Go templates during `zarf dev template` will be `[[ ]]`. This will separate package templates from the standard Go template delimiter `{{ }}`, which is used during on-deploy actions.
 
 ### User Stories (Optional)
 
@@ -481,7 +481,7 @@ How will security be reviewed, and by whom?
 How will UX be reviewed, and by whom?
 -->
 
-The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result.
+The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. The docs website added a page for migration to inform users how to switch https://docs.zarf.dev/best-practices/data-injections-migration/.
 
 The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to its replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables.
 
@@ -500,14 +500,14 @@ The ZarfChart object will be restructured to match the code block below. Exactly
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior.
 
-Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top level `version` field to the right sub object, or drop it when not applicable.
+Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
 type ZarfChart struct {
 	// The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo.
 	Name string `json:"name"`
-  // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1
+  // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
   version string
 	// The Helm repo where the chart is stored
 	HelmRepo HelmRepoSource `json:"helmRepo,omitempty"`
@@ -521,29 +521,29 @@ type ZarfChart struct {
 	Namespace string `json:"namespace,omitempty"`
 	// The name of the Helm release to create (defaults to the Zarf name of the chart).
 	ReleaseName string `json:"releaseName,omitempty"`
-	// Whether to not wait for chart resources to be ready before continuing.
+	// Whether to wait for chart resources to be ready before continuing.
 	Wait *bool `json:"wait,omitempty"`
 	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
-  // [alpha] List of values sources to their Helm override target
+  // [alpha] List of value sources mapped to their Helm override targets.
 	Values []ZarfChartValue `json:"values,omitempty"`
 }
 
 // HelmRepoSource represents a Helm chart stored in a Helm repository.
 type HelmRepoSource struct {
-	// The name of a chart within a Helm repository
+	// The name of a chart within a Helm repository.
 	RepoName string `json:"repoName,omitempty"`
-	// The URL of the chart repository where the helm chart is stored.
+	// The URL of the chart repository where the Helm chart is stored.
 	URL string `json:"url"`
-  // The version of the chart to deploy; for git-based charts this is also the tag of the git repo by default (when not using the '@' syntax for 'repos').
+  // The version of the chart to deploy; for Git-based charts this is also the tag of the Git repo by default (when not using the '@' syntax for 'repos').
 	Version string `json:"version"`
 }
 
 // GitRepoSource represents a Helm chart stored in a Git repository.
 type GitRepoSource struct {
-	// The URL of the git repository where the helm chart is stored.
+	// The URL of the Git repository where the Helm chart is stored.
 	URL string `json:"url"`
-	// The subdirectory to the chart within a git repo.
+	// The subdirectory containing the chart within a Git repo.
 	Path string `json:"path,omitempty"`
 }
 
@@ -555,7 +555,7 @@ type LocalRepoSource struct {
 
 // OCISource represents a Helm chart stored in an OCI registry.
 type OCISource struct {
-	// The URL of the OCI registry where the helm chart is stored.
+	// The URL of the OCI registry where the Helm chart is stored.
 	URL     string `json:"url"`
 	Version string `json:"version"`
 }
@@ -578,7 +578,7 @@ type ComponentConfig struct {
 	// A single component definition that applies in all contexts.
 	Component *Component `json:"component,omitempty"`
 	// A list of component variants, each with a distinct .only filter. Use this when the
-	// component has different definitions for different flavors, OSs, or architectures.
+	// component has different definitions for different flavors, OSes, or architectures.
 	Variants []Variant `json:"variants,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values ZarfValues `json:"values,omitempty"`
@@ -604,7 +604,7 @@ type Component struct {
 	Repos []string `json:"repos,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
 	Actions ZarfComponentActions `json:"actions,omitempty"`
-  // Features of the Zarf CLI
+  // Features of the Zarf CLI.
   Features ZarfComponentFeatures `json:"features,omitempty"`
 }
 
@@ -702,7 +702,7 @@ If this feature will eventually be deprecated, plan for it:
 - Wait at least two versions before fully removing it.
 -->
 
-The v1beta1 schema will not have an alpha/beta/GA phase. It will follow the graduation criteria laid out by [0048-schema-update-process](../0048-schema-update-process/README.md#graduation-criteria).
+The v1beta1 schema will not have an alpha/beta/GA phase. It will follow the graduation criteria laid out in [0048-schema-update-process](../0048-schema-update-process/README.md#graduation-criteria).
 
 Deprecation:
 - This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version is generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year.
@@ -762,7 +762,7 @@ Why should this ZEP _not_ be implemented?
 -->
 
 ### Component Import Reworks
-Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this re-write should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
+Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
 ## Alternatives
 
@@ -774,4 +774,4 @@ information to express the idea and why it was not acceptable.
 
 ### Component Import Schema
 
-Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.only` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allows for builtin schema validation, requiring the `.only` key with `.variants[]` but not with `.component`.
\ No newline at end of file
+Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.only` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.only` key with `.variants[]` but not with `.component`.
\ No newline at end of file

From 2946b0ecf26cb5f56803fad1df54641dd2cf78fc Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 12:34:58 -0400
Subject: [PATCH 064/131] logical fixes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0048-schema-update-process/README.md |  2 +-
 0051-v1beta1-schema/README.md        | 14 +++++++-------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/0048-schema-update-process/README.md b/0048-schema-update-process/README.md
index 5f130b0..4a768ea 100644
--- a/0048-schema-update-process/README.md
+++ b/0048-schema-update-process/README.md
@@ -186,7 +186,7 @@ As a package creator, I want to create and publish packages using the newer API
 
 #### Story 3
 
-As a package creator, I want to update my package definition to the v1beta1 schema, so I run `zarf dev upgrade-schema --to v1beta1` with a zarf.yaml in my current directory and it outputs the converted package definition to stdout.
+As a package creator, I want to update my package definition to the v1beta1 schema, so I run `zarf dev upgrade-schema . --to v1beta1 > zarf.yaml` against the directory containing my zarf.yaml. The command writes the converted definition to stdout, replacing my existing zarf.yaml.
 
 #### Story 4
 
diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 218409a..7f86001 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -130,7 +130,7 @@ What is out of scope for this ZEP? Listing non-goals helps to focus discussion
 and make progress.
 -->
 
-- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-update-process](https://github.com/zarf-dev/proposals/pull/49).
+- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-update-process](../0048-schema-update-process/README.md).
 
 ## Proposal
 
@@ -142,7 +142,7 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev upgrade-schema`. `apiVersion` will be a required field in v1beta1.
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. `apiVersion` will be a required field in v1beta1. Users will be able to upgrade there package definitions using `zarf dev upgrade-schema`, which writes the converted definition to stdout. 
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key.
 
@@ -194,9 +194,9 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain init logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators [#4528](https://github.com/zarf-dev/zarf/issues/4528) and leave little room for configurability.
 
-There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures Features are only used in packages that are `Kind: ZarfInitConfig`. This validation will run after the import chain is resolved.
+There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures Features are only used in packages that are `Kind: ZarfInitConfig` in `internal/api/v1beta1/validate.go`.
 
-View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity, given Zarf Features are the only difference.
+View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
 
 ```yaml
 - name: zarf-seed-registry
@@ -293,7 +293,7 @@ components:
           - values.yaml
 ```
 
-I want to upgrade to the v1beta1 schema, so I run `zarf dev upgrade-schema`, which produces:
+I want to upgrade to the v1beta1 schema, so I run `zarf dev upgrade-schema . > zarf.yaml`. Which produces:
 
 ```yaml
 apiVersion: v1beta1
@@ -500,7 +500,7 @@ The ZarfChart object will be restructured to match the code block below. Exactly
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior.
 
-Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
+Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
 
 ```go
 // ZarfChart defines a helm chart to be deployed.
@@ -676,7 +676,7 @@ when drafting this test plan.
 existing tests to make this code solid enough prior to committing the changes necessary
 to implement this proposal.
 
-There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears GA, existing tests will shift to use the v1beta1 schema.
+There will be e2e tests for creating, deploying, and publishing a v1beta1 package. Existing tests will shift to use the v1beta1 schema over time.
 
 ### Graduation Criteria
 

From 0a9e8068755979633af5c7aa1380bc4aadd38573 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 12:41:53 -0400
Subject: [PATCH 065/131] fix zarf.yaml

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 0051-v1beta1-schema/zarf.yaml | 7 ++-----
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7f86001..e664628 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -287,7 +287,7 @@ components:
         version: 6.4.0
         namespace: podinfo-from-repo
         url: https://stefanprodan.github.io/podinfo
-        repoName: podinfo
+        name: podinfo
         releaseName: cool-release-name
         valuesFiles:
           - values.yaml
@@ -532,7 +532,7 @@ type ZarfChart struct {
 // HelmRepoSource represents a Helm chart stored in a Helm repository.
 type HelmRepoSource struct {
 	// The name of a chart within a Helm repository.
-	RepoName string `json:"repoName,omitempty"`
+	Name string `json:"name,omitempty"`
 	// The URL of the chart repository where the Helm chart is stored.
 	URL string `json:"url"`
   // The version of the chart to deploy; for Git-based charts this is also the tag of the Git repo by default (when not using the '@' syntax for 'repos').
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 3b26030..c11f210 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -1,5 +1,5 @@
 kind: ZarfInitConfig
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 metadata:
   name: everything-zarf-package
   description: A zarf package with a non empty value for every key - this demonstrates the changes proposed by ZEP-0051
@@ -23,9 +23,6 @@ build: # Everything here is created by Zarf not be users
   version: v1.0.0
   migrations:
     - scripts-to-actions
-  versionRequirements:
-    - version: 0.65.0
-      reason: "the package structure of Helm charts changed"
   registryOverrides:
     gcr.io: my-gcr.com
   differential: true
@@ -104,7 +101,7 @@ components:
     extractPath: /path/to/extract
     template: false # Disable go-template processing for this file
   images:
-    - name: - podinfo@v1
+    - name: podinfo@v1
       source: "registry" # optional - registry is the default value
   imageArchives:
   - path: podinfo.tar

From 65172b020a00f0163921cac56d04ce85d7f2c019 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 12:49:54 -0400
Subject: [PATCH 066/131] fix errors

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 31 ++++++++++++++-----------------
 1 file changed, 14 insertions(+), 17 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index e664628..7dc1a61 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,7 +142,7 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. `apiVersion` will be a required field in v1beta1. Users will be able to upgrade there package definitions using `zarf dev upgrade-schema`, which writes the converted definition to stdout. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. `apiVersion` will be a required field in v1beta1. Users will be able to upgrade their package definitions using `zarf dev upgrade-schema`, which writes the converted definition to stdout. 
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key.
 
@@ -166,7 +166,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
-- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes).
+- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
 - `.components.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon.
 
@@ -224,7 +224,7 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using the new command `zarf component publish <component-file>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
+Remote components will be published using the new command `zarf component publish <component-file> <oci-repo>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
 
@@ -296,13 +296,10 @@ components:
 I want to upgrade to the v1beta1 schema, so I run `zarf dev upgrade-schema . > zarf.yaml`. Which produces:
 
 ```yaml
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 kind: ZarfPackageConfig
 metadata:
   name: helm-charts
-  description: Example showcasing multiple ways to deploy helm charts
-  version: 0.0.1
-
 components:
   - name: demo-helm-charts
     optional: false  # Changed from `required: true`
@@ -349,7 +346,7 @@ As a package creator, I have a logging component that I maintain locally and wan
 First, I define my local logging component in `logging.yaml`:
 
 ```yaml
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 kind: ZarfComponentConfig
 metadata:
   name: logging
@@ -366,7 +363,7 @@ component:
 My teammate has published a monitoring component to our registry. Its source file, `monitoring.yaml`, looked like this before publishing:
 
 ```yaml
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 kind: ZarfComponentConfig
 metadata:
   name: monitoring
@@ -392,7 +389,7 @@ zarf component publish monitoring.yaml oci://ghcr.io/my-org/components
 Now I create a v1beta1 package that imports both components -- the local one by file path and the remote one by URL:
 
 ```yaml
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 kind: ZarfPackageConfig
 metadata:
   name: observability
@@ -418,7 +415,7 @@ zarf package create
 As a package creator, I want to template image references and metadata into my package at build time. I write a `zarf.tpl.yaml` that uses Go templates with the `[[ ]]` delimiter:
 
 ```yaml
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 kind: ZarfPackageConfig
 metadata:
   name: app
@@ -445,17 +442,17 @@ zarf dev template --set ENVIRONMENT=personal --set MY_IMAGE=ghcr.io/my-org/my-im
 This produces `zarf.gen.yaml`:
 
 ```yaml
-apiVersion: v1beta1
+apiVersion: zarf.dev/v1beta1
 kind: ZarfPackageConfig
 metadata:
-  name: my-app
-  description: "my-app personal"
+  name: app
+  description: "app personal"
 
 components:
-  - name: my-app
+  - name: app
     charts:
-      - name: my-app
-        namespace: my-app
+      - name: app
+        namespace: app
         oci:
           url: oci://ghcr.io/my-org/charts/my-app
           version: 1.0.0

From 0129f153765d740213516bd4ea002b20b8cf0000 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 15 Apr 2026 13:48:30 -0400
Subject: [PATCH 067/131] updates for better flow

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7dc1a61..b183ba4 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -92,7 +92,7 @@ feedback and reduce unnecessary changes.
 [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/
 -->
 
-Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the opportunity to make these changes.
+Several fields in the v1alpha1 ZarfPackageConfig should be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. Introducing a new schema version, v1beta1, provides the opportunity to make these changes.
 
 ## Motivation
 
@@ -152,10 +152,10 @@ The v1beta1 schema will remove, replace, and rename several fields. View this [z
 
 If a package has these fields defined then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
 
-- `.components.[x].group` will be removed. Users should use `components[x].only.flavor` instead.
-- `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926).
-- `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev upgrade-schema`.
-- `.metadata.yolo` will be removed. Its successor will be connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
+- `.components.[x].group` will be removed. A similar functionality was introduced with the field `components[x].only.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
+- `.components.[x].dataInjections` will be removed. https://docs.zarf.dev/best-practices/data-injections-migration/ details migrating off of this field.
+- `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
+- `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
 - `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig).
 
 #### Replaced / Restructured Fields
@@ -188,15 +188,15 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 #### Wait Changes
 
-There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf will wait until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks.
+There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf waits until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks.
 
 #### Zarf Features
 
-In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain init logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators [#4528](https://github.com/zarf-dev/zarf/issues/4528) and leave little room for configurability.
+In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators, [#4528](https://github.com/zarf-dev/zarf/issues/4528), and leave little room for configurability.
 
-There will be a new "features" key on components that should make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures Features are only used in packages that are `Kind: ZarfInitConfig` in `internal/api/v1beta1/validate.go`.
+A new "features" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures Features are only used in packages that are `Kind: ZarfInitConfig`. There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
 
-View the full schema in [Zarf Features Schema](#zarf-features-schema). There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
+View the full schema in [Zarf Features Schema](#zarf-features-schema). 
 
 ```yaml
 - name: zarf-seed-registry
@@ -212,13 +212,13 @@ View the full schema in [Zarf Features Schema](#zarf-features-schema). There wil
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only by v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must define exactly one of `component` or `variants`. The `component` field is a single object representing a component that is always importable. The `variants` field is a list of components where each entry must specify the `.only` key to define when that variant applies (e.g. flavors, OSes, or architectures). If the `.only` key has the same value for two variants, the user will receive an error. View the schema of this object in [design details](#zarf-component-config-schema).
+A ZarfComponentConfig must either the `component` or `variants` field. The `component` field is a single object representing a component that is importable by any package. The `variants` field is a list of components where each entry must specify the `.only` to differentiate itself from the other components (e.g. flavors, OSes, or architectures). Zarf will error if two components under `variants` have the same value for `.only`. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
 The `.import.path` field will not accept directories; users will give the file path to the ZarfComponentConfig file they are importing.
 
-The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint, inspect, and find-images) will accept component config files. For instance, `zarf dev inspect definition my-component-config.yaml`.
+The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint, inspect, and find-images) will accept component config files. For example, `zarf dev inspect definition my-component-config.yaml`.
 
 #### Remote Components
 
@@ -234,7 +234,7 @@ The Zarf v1alpha1 schema allows for package templates during create using the ##
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.
 
-`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml`, Zarf will template the file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
+`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
 
 Package templates will be required to have a value; otherwise the command will fail.
 

From 55acb1aeb6b013cfbc3993b0adda3a2cc4bd7538 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 17 Apr 2026 15:11:16 -0400
Subject: [PATCH 068/131] change back update schema zep

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0048-schema-update-process/zep.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/0048-schema-update-process/zep.yaml b/0048-schema-update-process/zep.yaml
index a2abf05..4d0b4e7 100644
--- a/0048-schema-update-process/zep.yaml
+++ b/0048-schema-update-process/zep.yaml
@@ -12,17 +12,17 @@ approvers:
   - "@zarf-dev"
 
 see-also:
-  # Will add the v1 schema here when applicable
+  - "/0051-v1beta1-schema"
 replaces:
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: ga
+stage: alpha
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
 # worked on.
-latest-milestone: "v0.74.2"
+latest-milestone: "v0.75.0"
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
-  stable: "v0.74.2"
+  stable: "TBD"

From e9e29150a6731c1f0e4dfe8ab782833f177e1547 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 17 Apr 2026 16:08:05 -0400
Subject: [PATCH 069/131] clarify v1alpha1

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index b183ba4..8c7a217 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -142,7 +142,9 @@ desired outcome and how success will be measured. The "Design Details" section
 below is for the real nitty-gritty.
 -->
 
-Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. `apiVersion` will be a required field in v1beta1. Users will be able to upgrade their package definitions using `zarf dev upgrade-schema`, which writes the converted definition to stdout. 
+Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. Until v1alpha is removed, if `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. `apiVersion` will be a required field in v1beta1 and all future schemas. 
+
+Users will be able to upgrade their package definitions using `zarf dev upgrade-schema`, which writes the converted definition to stdout. 
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key.
 

From 95ba4c595583356c80b7eee6d77b2f4d6fc85e8f Mon Sep 17 00:00:00 2001
From: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
Date: Mon, 20 Apr 2026 07:48:35 -0400
Subject: [PATCH 070/131] Update 0051-v1beta1-schema/README.md

Co-authored-by: Brandt Keller <43887158+brandtkeller@users.noreply.github.com>
Signed-off-by: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 8c7a217..40d4a2f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -214,7 +214,7 @@ View the full schema in [Zarf Features Schema](#zarf-features-schema).
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only by v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must either the `component` or `variants` field. The `component` field is a single object representing a component that is importable by any package. The `variants` field is a list of components where each entry must specify the `.only` to differentiate itself from the other components (e.g. flavors, OSes, or architectures). Zarf will error if two components under `variants` have the same value for `.only`. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
+A ZarfComponentConfig must declare either the `component` or `variants` field. The `component` field is a single object representing a component that is importable by any package. The `variants` field is a list of components where each entry must specify the `.only` to differentiate itself from the other components (e.g. flavors, OSes, or architectures). Zarf will error if two components under `variants` have the same value for `.only`. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 

From 17a5140c192bf39d2ea7f3ce65446fa5a9239b7a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Apr 2026 08:07:55 -0400
Subject: [PATCH 071/131] alternative

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0048-schema-update-process/README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/0048-schema-update-process/README.md b/0048-schema-update-process/README.md
index 4a768ea..d8b51c7 100644
--- a/0048-schema-update-process/README.md
+++ b/0048-schema-update-process/README.md
@@ -472,6 +472,10 @@ not need to be as detailed as the proposal, but should include enough
 information to express the idea and why it was not acceptable.
 -->
 
+### Use only one API version
+
+Instead of introducing a new schema, we could overtime remove and introduce fields on the existing package schema. This was rejected as we believe a new schema will provide a more intuitive experience for developers and maintainers. For instance, attempting to implement the proposed Helm changes would result in a large, confusing schema. Likewise, it would be difficult to change defaults, such as moving from required to optional, since we wouldn't have a new API version to signal that there is a breaking change. Additionally, removing deprecated fields such as `dataInjections` would require a major version change. Keeping the API version and CLI version decoupled allows flexibility to make the changes we need.
+
 ### Public Facing Internal Type
 
 Rather than updating functions to accept a newer version of the schema, Zarf could have a publicly facing internal type that has every field from every version and use that throughout the SDK. The upside of this approach is that we would avoid breaking changes throughout the lifetime of the SDK. The downside is that it would make it easy for anyone using the SDK to set deprecated fields. It would also make it confusing and unclear which fields attach to which versions. 

From 391052e0cc2de1b5ab6b5024e2aaa55d7469248b Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Apr 2026 08:20:22 -0400
Subject: [PATCH 072/131] images import

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 40d4a2f..73b6964 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -170,7 +170,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
-- `.components.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon.
+- `.components.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append, to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
 
 #### Renamed Fields
 

From 3d2e57cd7a0648a2349138c45ecadb2204d0a513 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Apr 2026 08:26:46 -0400
Subject: [PATCH 073/131] add services

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 73b6964..6a5bf7e 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -184,7 +184,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 ### New Fields
 
-- `.components[x].features` will be introduced to avoid magic names in Init package components. See [Zarf Features](#zarf-features) for more details.
+- `.components[x].services` will be introduced to avoid magic names in Init package components. See [Zarf Services](#zarf-services) for more details.
 
 ### Behavior Changes
 
@@ -192,17 +192,17 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf waits until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks.
 
-#### Zarf Features
+#### Zarf Services
 
 In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators, [#4528](https://github.com/zarf-dev/zarf/issues/4528), and leave little room for configurability.
 
-A new "features" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.features.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent features don't allow setting specific values, as those features already have Helm charts. There will be validation that ensures Features are only used in packages that are `Kind: ZarfInitConfig`. There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
+A new "services" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.services.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent services don't allow setting specific values, as those services already have Helm charts. There will be validation that ensures Services are only used in packages that are `Kind: ZarfInitConfig`. There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
 
-View the full schema in [Zarf Features Schema](#zarf-features-schema). 
+View the full schema in [Zarf Services Schema](#zarf-services-schema). 
 
 ```yaml
 - name: zarf-seed-registry
-  features:
+  services:
     isRegistry: true
     injector:
       enabled: true
@@ -603,8 +603,8 @@ type Component struct {
 	Repos []string `json:"repos,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
 	Actions ZarfComponentActions `json:"actions,omitempty"`
-  // Features of the Zarf CLI.
-  Features ZarfComponentFeatures `json:"features,omitempty"`
+  // Zarf CLI services and infrastructure such as the registry, injector, and agent.
+  Services ZarfComponentServices `json:"services,omitempty"`
 }
 
 // Variant is a component definition with a required filter for when it applies.
@@ -637,12 +637,12 @@ type ComponentPublishData struct {
 }
 ```
 
-### Zarf Features Schema
+### Zarf Services Schema
 
-The schema for Zarf Features:
+The schema for Zarf Services:
 
 ```go
-type ZarfComponentFeatures struct {
+type ZarfComponentServices struct {
   IsRegistry bool       `json:"isRegistry,omitempty"`
   Injector   *Injector  `json:"injector,omitempty"`
   IsAgent    bool       `json:"isAgent,omitempty"`
@@ -752,7 +752,7 @@ Major milestones might include:
 -->
 
 - 2025-10-21: Proposal submitted
-- 2026-02-12: Introduced Zarf Component Config, package templating changes, and Zarf features
+- 2026-02-12: Introduced Zarf Component Config, package templating changes, and Zarf services
 
 ## Drawbacks
 

From a53c7b463afc88ed26747e5d1054bb808f0f9f80 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Apr 2026 12:23:24 -0400
Subject: [PATCH 074/131] more detail as to why we avoid skeleton templates

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 6a5bf7e..b5b5056 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -228,7 +228,7 @@ Skeleton packages will be replaced by remote components. Instead of publishing a
 
 Remote components will be published using the new command `zarf component publish <component-file> <oci-repo>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
 
-Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. See [Package Templates](#package-templates) for more detail.
+Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. By templating before publish, we avoid issues with validating a non-templated package ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and stay aligned with the overall [Package Templates](#package-templates) strategy.
 
 ### Package Templates
 

From b339bfaff2e25119f5d9b19918c3613fb314393b Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 20 Apr 2026 12:32:37 -0400
Subject: [PATCH 075/131] update zep.yaml

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0048-schema-update-process/zep.yaml | 2 +-
 0051-v1beta1-schema/zep.yaml        | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/0048-schema-update-process/zep.yaml b/0048-schema-update-process/zep.yaml
index 4d0b4e7..6a25c77 100644
--- a/0048-schema-update-process/zep.yaml
+++ b/0048-schema-update-process/zep.yaml
@@ -16,7 +16,7 @@ see-also:
 replaces:
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: alpha
+stage: ""
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml
index 458cf8a..d598ef7 100644
--- a/0051-v1beta1-schema/zep.yaml
+++ b/0051-v1beta1-schema/zep.yaml
@@ -15,7 +15,7 @@ see-also:
   - "/0048-schema-upgrade-process"
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: ga
+stage: ""
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
@@ -24,6 +24,4 @@ latest-milestone: ""
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
-  alpha: "NA"
-  beta: "TBD"
   stable: "TBD""

From 7f88d60227306b6afa775a34d457c0b0458651a7 Mon Sep 17 00:00:00 2001
From: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
Date: Wed, 22 Apr 2026 13:37:24 -0400
Subject: [PATCH 076/131] Apply suggestions from code review

Co-authored-by: Maciej Szulik <soltysh@gmail.com>
Signed-off-by: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
---
 0048-schema-update-process/README.md | 2 +-
 0051-v1beta1-schema/zarf.yaml        | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/0048-schema-update-process/README.md b/0048-schema-update-process/README.md
index d8b51c7..65841c1 100644
--- a/0048-schema-update-process/README.md
+++ b/0048-schema-update-process/README.md
@@ -474,7 +474,7 @@ information to express the idea and why it was not acceptable.
 
 ### Use only one API version
 
-Instead of introducing a new schema, we could overtime remove and introduce fields on the existing package schema. This was rejected as we believe a new schema will provide a more intuitive experience for developers and maintainers. For instance, attempting to implement the proposed Helm changes would result in a large, confusing schema. Likewise, it would be difficult to change defaults, such as moving from required to optional, since we wouldn't have a new API version to signal that there is a breaking change. Additionally, removing deprecated fields such as `dataInjections` would require a major version change. Keeping the API version and CLI version decoupled allows flexibility to make the changes we need.
+Instead of introducing a new schema, we could over time remove and introduce fields on the existing package schema. This was rejected as we believe a new schema will provide a more intuitive experience for developers and maintainers. For instance, attempting to implement the proposed Helm changes would result in a large, confusing schema. Likewise, it would be difficult to change defaults, such as moving from required to optional, since we wouldn't have a new API version to signal that there is a breaking change. Additionally, removing deprecated fields such as `dataInjections` would require a major version change. Keeping the API version and CLI version decoupled allows flexibility to make the changes we need.
 
 ### Public Facing Internal Type
 
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index c11f210..7030657 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -15,7 +15,7 @@ metadata:
     image: https://my-image-url-to-use-in-deprecated-zarf-ui
     anyway-you-want-it: thats-the-way-you-need-it
   allowNamespaceOverride: true
-build: # Everything here is created by Zarf not be users
+build: # Everything here is created by Zarf not by users
   terminal: my-computer
   user: my-user
   architecture: amd64
@@ -79,7 +79,7 @@ components:
     - sourcePath: ".app.name"
       targetPath: ".appName"
     schemaValidation: true
-    helmRepo: # Only one of helm, git, oci, url, or local is allowed
+    helmRepo: # Only one of helmRepo, git, oci, url, or local is allowed
       url: https://stefanprodan.github.io/podinfo
       name: podinfo # replaces repoName since it's only applicable in this situation
       version: 6.4.0

From d2949394ec4d24b0015198735376438dae0012ac Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 13:38:13 -0400
Subject: [PATCH 077/131] remove omit empty

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index b5b5056..f0b32bc 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -568,7 +568,7 @@ The schema for the Zarf component config will look like so:
 // ComponentConfig is the top-level structure of a Zarf component config file.
 type ComponentConfig struct {
 	// The API version of the component config.
-	APIVersion string `json:"apiVersion,omitempty" jsonschema:"enum=zarf.dev/v1beta1"`
+	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
 	// The kind of component config.
 	Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
 	// Component metadata.

From f74b7c9ea7c31f33493b7a14e32a30ea993e9bb2 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 13:39:53 -0400
Subject: [PATCH 078/131] update comment

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index f0b32bc..6908a28 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -534,7 +534,7 @@ type HelmRepoSource struct {
 	Name string `json:"name,omitempty"`
 	// The URL of the chart repository where the Helm chart is stored.
 	URL string `json:"url"`
-  // The version of the chart to deploy; for Git-based charts this is also the tag of the Git repo by default (when not using the '@' syntax for 'repos').
+  // The version of the chart in the Helm repository.
 	Version string `json:"version"`
 }
 

From e753a7ebe714c9ec7a0811e0067abe1b20b070ca Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 13:41:29 -0400
Subject: [PATCH 079/131] make chart fields pointers

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 6908a28..2f3fb02 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -509,13 +509,13 @@ type ZarfChart struct {
   // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
   version string
 	// The Helm repo where the chart is stored
-	HelmRepo HelmRepoSource `json:"helmRepo,omitempty"`
+	HelmRepo *HelmRepoSource `json:"helmRepo,omitempty"`
 	// The Git repo where the chart is stored
-	Git GitRepoSource `json:"git,omitempty"`
+	Git *GitRepoSource `json:"git,omitempty"`
 	// The local path where the chart is stored
-	Local LocalRepoSource `json:"local,omitempty"`
+	Local *LocalRepoSource `json:"local,omitempty"`
 	// The OCI registry where the chart is stored
-	OCI OCISource `json:"oci,omitempty"`
+	OCI *OCISource `json:"oci,omitempty"`
 	// The namespace to deploy the chart to.
 	Namespace string `json:"namespace,omitempty"`
 	// The name of the Helm release to create (defaults to the Zarf name of the chart).

From 9f550611a84e3c5202dc9d0be803453c7f9b3db6 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 13:57:22 -0400
Subject: [PATCH 080/131] update component to target

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 13 +++++++------
 0051-v1beta1-schema/zarf.yaml |  2 +-
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 2f3fb02..82daffe 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -154,7 +154,7 @@ The v1beta1 schema will remove, replace, and rename several fields. View this [z
 
 If a package has these fields defined then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
 
-- `.components.[x].group` will be removed. A similar functionality was introduced with the field `components[x].only.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
+- `.components.[x].group` will be removed. A similar functionality was introduced with the field `components[x].target.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
 - `.components.[x].dataInjections` will be removed. https://docs.zarf.dev/best-practices/data-injections-migration/ details migrating off of this field.
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
 - `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
@@ -181,6 +181,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
+- `.components.[x].only` will be renamed to `.components.[x].target`.
 
 ### New Fields
 
@@ -214,7 +215,7 @@ View the full schema in [Zarf Services Schema](#zarf-services-schema).
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only by v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must declare either the `component` or `variants` field. The `component` field is a single object representing a component that is importable by any package. The `variants` field is a list of components where each entry must specify the `.only` to differentiate itself from the other components (e.g. flavors, OSes, or architectures). Zarf will error if two components under `variants` have the same value for `.only`. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
+A ZarfComponentConfig must declare either the `component` or `variants` field. The `component` field is a single object representing a component that is importable by any package. The `variants` field is a list of components where each entry must specify the `.target` to differentiate itself from the other components (e.g. flavors, OSes, or architectures). Zarf will error if two components under `variants` have the same value for `.target`. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
@@ -226,7 +227,7 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using the new command `zarf component publish <component-file> <oci-repo>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.only` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
+Remote components will be published using the new command `zarf component publish <component-file> <oci-repo>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.target` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. By templating before publish, we avoid issues with validating a non-templated package ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and stay aligned with the overall [Package Templates](#package-templates) strategy.
 
@@ -576,7 +577,7 @@ type ComponentConfig struct {
   // Exactly one of Component or Variants must be set.
 	// A single component definition that applies in all contexts.
 	Component *Component `json:"component,omitempty"`
-	// A list of component variants, each with a distinct .only filter. Use this when the
+	// A list of component variants, each with a distinct .target filter. Use this when the
 	// component has different definitions for different flavors, OSes, or architectures.
 	Variants []Variant `json:"variants,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
@@ -611,7 +612,7 @@ type Component struct {
 type Variant struct {
 	Component
 	// Filter when this variant is included in package creation or deployment.
-	Only ZarfComponentOnlyTarget `json:"only"`
+	Target ZarfComponentTarget `json:"target"`
 }
 
 // ZarfComponentMetadata holds metadata about a component config.
@@ -773,4 +774,4 @@ information to express the idea and why it was not acceptable.
 
 ### Component Import Schema
 
-Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.only` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.only` key with `.variants[]` but not with `.component`.
\ No newline at end of file
+Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
\ No newline at end of file
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 7030657..c78fd15 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -41,7 +41,7 @@ components:
 - name: a-component
   description: Zarf description
   optional: false # Component is required (default behavior)
-  only:
+  target:
     localOS: darwin
     cluster:
       architecture: amd64

From 231d6b7bff78a3cbe68b465cacf4e58051905f67 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 14:00:47 -0400
Subject: [PATCH 081/131] remove distro

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 1 +
 0051-v1beta1-schema/zarf.yaml | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 82daffe..e828252 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -159,6 +159,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
 - `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
 - `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig).
+- `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are plans to use it currently.
 
 #### Replaced / Restructured Fields
 
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index c78fd15..2d9e144 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -45,8 +45,6 @@ components:
     localOS: darwin
     cluster:
       architecture: amd64
-      distros:
-      - ubuntu
     flavor: a-flavor # this will only be used when there are multiple components
   import:
     path: ABCD # Only path or URL will be used, not both

From a80543ffa74992fbed25f7b0d2e25b8fd5316ba6 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 14:26:58 -0400
Subject: [PATCH 082/131] talk about inling cluster architecture

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index e828252..7f64936 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -168,6 +168,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
+- `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).

From d70db745db632c15929ab2292db98f073f03b08f Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 14:28:16 -0400
Subject: [PATCH 083/131] additional clarifying line

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7f64936..a8cfe4e 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -168,7 +168,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
-- `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`
+- `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`. Since `.cluster.distro` will be removed, the `.cluster` parent field will be deleted. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).

From bf67bd2ab01a0401ac5313e5958f0a8c7e98b865 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 14:35:58 -0400
Subject: [PATCH 084/131] add one of to the schema

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index a8cfe4e..c314771 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -578,10 +578,10 @@ type ComponentConfig struct {
 	Metadata ZarfComponentMetadata `json:"metadata"`
   // Exactly one of Component or Variants must be set.
 	// A single component definition that applies in all contexts.
-	Component *Component `json:"component,omitempty"`
+	Component *Component `json:"component,omitempty" jsonschema:"oneof_required=component"`
 	// A list of component variants, each with a distinct .target filter. Use this when the
 	// component has different definitions for different flavors, OSes, or architectures.
-	Variants []Variant `json:"variants,omitempty"`
+	Variants []Variant `json:"variants,omitempty" jsonschema:"oneof_required=variants"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values ZarfValues `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.

From 54d6d264cb2f1d89f502734ed78cbadae685f7a4 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 15:06:43 -0400
Subject: [PATCH 085/131] use full word repository

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 35 ++++++++++++++++++-----------------
 0051-v1beta1-schema/zarf.yaml |  6 +++---
 2 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c314771..75c848e 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -184,6 +184,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 - `.components.[x].only` will be renamed to `.components.[x].target`.
+- `.components.[x].repos` will be renamed to `.components.[x].repositories`
 
 ### New Fields
 
@@ -335,7 +336,7 @@ components:
 
       - name: podinfo-repo
         namespace: podinfo-from-repo
-        helmRepo:
+        helmRepository:
           url: https://stefanprodan.github.io/podinfo
           name: podinfo  # Changed from `repoName`
           version: 6.4.0
@@ -377,7 +378,7 @@ component:
   charts:
     - name: kube-prometheus-stack
       namespace: monitoring
-      helmRepo:
+      helmRepository:
         url: https://prometheus-community.github.io/helm-charts
         name: kube-prometheus-stack
         version: 60.0.0
@@ -498,9 +499,9 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helmRepo`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
-During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior.
+During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.git.URL`. This is consistent with the current Zarf behavior.
 
 Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
 
@@ -511,12 +512,12 @@ type ZarfChart struct {
 	Name string `json:"name"`
   // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
   version string
-	// The Helm repo where the chart is stored
-	HelmRepo *HelmRepoSource `json:"helmRepo,omitempty"`
-	// The Git repo where the chart is stored
-	Git *GitRepoSource `json:"git,omitempty"`
+	// The Helm repository where the chart is stored
+	HelmRepository *HelmRepositorySource `json:"helmRepository,omitempty"`
+	// The Git repository where the chart is stored
+	Git *GitSource `json:"git,omitempty"`
 	// The local path where the chart is stored
-	Local *LocalRepoSource `json:"local,omitempty"`
+	Local *LocalSource `json:"local,omitempty"`
 	// The OCI registry where the chart is stored
 	OCI *OCISource `json:"oci,omitempty"`
 	// The namespace to deploy the chart to.
@@ -531,8 +532,8 @@ type ZarfChart struct {
 	Values []ZarfChartValue `json:"values,omitempty"`
 }
 
-// HelmRepoSource represents a Helm chart stored in a Helm repository.
-type HelmRepoSource struct {
+// HelmRepositorySource represents a Helm chart stored in a Helm repository.
+type HelmRepositorySource struct {
 	// The name of a chart within a Helm repository.
 	Name string `json:"name,omitempty"`
 	// The URL of the chart repository where the Helm chart is stored.
@@ -541,16 +542,16 @@ type HelmRepoSource struct {
 	Version string `json:"version"`
 }
 
-// GitRepoSource represents a Helm chart stored in a Git repository.
-type GitRepoSource struct {
+// GitSource represents a Helm chart stored in a Git repository.
+type GitSource struct {
 	// The URL of the Git repository where the Helm chart is stored.
 	URL string `json:"url"`
 	// The subdirectory containing the chart within a Git repo.
 	Path string `json:"path,omitempty"`
 }
 
-// LocalRepoSource represents a Helm chart stored locally.
-type LocalRepoSource struct {
+// LocalSource represents a Helm chart stored locally.
+type LocalSource struct {
 	// The path to a local chart's folder or .tgz archive.
 	Path string `json:"path"`
 }
@@ -602,8 +603,8 @@ type Component struct {
 	Images []ZarfImage `json:"images,omitempty"`
 	// List of Tar files of images to bring into the package.
 	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
-	// List of git repos to include in the package.
-	Repos []string `json:"repos,omitempty"`
+	// List of git repositories to include in the package.
+	Repositories []string `json:"repositories,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
 	Actions ZarfComponentActions `json:"actions,omitempty"`
   // Zarf CLI services and infrastructure such as the registry, injector, and agent.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 2d9e144..549da00 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -77,7 +77,7 @@ components:
     - sourcePath: ".app.name"
       targetPath: ".appName"
     schemaValidation: true
-    helmRepo: # Only one of helmRepo, git, oci, url, or local is allowed
+    helmRepository: # Only one of helmRepository, git, oci, url, or local is allowed
       url: https://stefanprodan.github.io/podinfo
       name: podinfo # replaces repoName since it's only applicable in this situation
       version: 6.4.0
@@ -105,8 +105,8 @@ components:
   - path: podinfo.tar
     images:
       - podinfo:local
-  repos:
-  - https://github.com/defenseunicorns/zarf
+  repositories:
+  - https://github.com/zarf-dev/zarf
   actions:
     onCreate:
       defaults:

From b9fca047007d13ca00643b3b5c5493d831f81d52 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 15:52:13 -0400
Subject: [PATCH 086/131] put a copy of the package.go

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 472 +++++++++++++++++++++++++++++++++
 1 file changed, 472 insertions(+)
 create mode 100644 0051-v1beta1-schema/package.go

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
new file mode 100644
index 0000000..a6a4483
--- /dev/null
+++ b/0051-v1beta1-schema/package.go
@@ -0,0 +1,472 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2021-Present The Zarf Authors
+
+// Package v1beta1 holds the definition of the v1beta1 Zarf Package.
+package v1beta1
+
+import (
+	"time"
+)
+
+// VariableType represents a type of a Zarf package variable.
+type VariableType string
+
+const (
+	// RawVariableType is the default type for a Zarf package variable.
+	RawVariableType VariableType = "raw"
+	// FileVariableType loads the variable contents from a file.
+	FileVariableType VariableType = "file"
+)
+
+// ZarfPackageKind is an enum of the different kinds of Zarf packages.
+type ZarfPackageKind string
+
+const (
+	// ZarfInitConfig is the kind of Zarf package used during `zarf init`.
+	ZarfInitConfig ZarfPackageKind = "ZarfInitConfig"
+	// ZarfPackageConfig is the default kind of Zarf package.
+	ZarfPackageConfig ZarfPackageKind = "ZarfPackageConfig"
+	// APIVersion is the api version of this package.
+	APIVersion string = "zarf.dev/v1beta1"
+)
+
+// ZarfPackage is the top-level structure of a Zarf package definition.
+type ZarfPackage struct {
+	// The API version of the Zarf package.
+	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
+	// The kind of Zarf package.
+	Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"`
+	// Package metadata.
+	Metadata ZarfMetadata `json:"metadata,omitempty"`
+	// Zarf-generated package build data.
+	Build ZarfBuildData `json:"build,omitempty"`
+	// List of components to deploy in this package.
+	Components []ZarfComponent `json:"components" jsonschema:"minItems=1"`
+	// Constant template values applied on deploy.
+	Constants []Constant `json:"constants,omitempty"`
+	// Variable template values applied on deploy.
+	Variables []InteractiveVariable `json:"variables,omitempty"`
+	// Values imports Zarf values files for templating and overriding Helm values.
+	Values ZarfValues `json:"values,omitempty"`
+	// Documentation files included in the package.
+	Documentation map[string]string `json:"documentation,omitempty"`
+}
+
+// ZarfMetadata holds information about the package.
+type ZarfMetadata struct {
+	// Name to identify this Zarf package.
+	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
+	// Additional information about this Zarf package.
+	Description string `json:"description,omitempty"`
+	// Generic string set by a package author to track the package version.
+	Version string `json:"version,omitempty"`
+	// Disable compression of this package.
+	Uncompressed bool `json:"uncompressed,omitempty"`
+	// The target cluster architecture for this package.
+	Architecture string `json:"architecture,omitempty" jsonschema:"example=arm64,example=amd64"`
+	// Annotations are key-value pairs that can be used to store metadata about the package.
+	Annotations map[string]string `json:"annotations,omitempty"`
+	// Whether to allow namespace overrides for this package.
+	AllowNamespaceOverride *bool `json:"allowNamespaceOverride,omitempty"`
+}
+
+// ZarfBuildData is written during package create to track details of the created package.
+type ZarfBuildData struct {
+	// The machine name that created this package.
+	Terminal string `json:"terminal,omitempty"`
+	// The username who created this package.
+	User string `json:"user,omitempty"`
+	// The architecture this package was created on.
+	Architecture string `json:"architecture"`
+	// The timestamp when this package was created.
+	Timestamp string `json:"timestamp"`
+	// The version of Zarf used to build this package.
+	Version string `json:"version"`
+	// Any migrations that have been run on this package.
+	Migrations []string `json:"migrations,omitempty"`
+	// Any registry domains that were overridden on package create when pulling images.
+	RegistryOverrides map[string]string `json:"registryOverrides,omitempty"`
+	// Whether this package was created with differential components.
+	Differential bool `json:"differential,omitempty"`
+	// The flavor of Zarf used to build this package.
+	Flavor string `json:"flavor,omitempty"`
+	// Requirements for specific Zarf versions needed to deploy this package.
+	VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"`
+	// Checksum of a checksums.txt file that contains checksums all the layers within the package.
+	AggregateChecksum string `json:"aggregateChecksum,omitempty"`
+}
+
+// VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement.
+type VersionRequirement struct {
+	// The minimum version of Zarf required.
+	Version string `json:"version"`
+	// The reason this version is required.
+	Reason string `json:"reason"`
+}
+
+// ZarfValues defines values files and schema for templating and overriding Helm values.
+type ZarfValues struct {
+	// List of values file paths to include.
+	Files []string `json:"files,omitempty"`
+	// Path to a JSON schema file for validating values.
+	Schema string `json:"schema,omitempty"`
+}
+
+// Variable represents a variable that has a value set programmatically.
+type Variable struct {
+	// The name to be used for the variable.
+	Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"`
+	// Whether to mark this variable as sensitive to not print it in the log.
+	Sensitive bool `json:"sensitive,omitempty"`
+	// Whether to automatically indent the variable's value (if multiline) when templating.
+	AutoIndent bool `json:"autoIndent,omitempty"`
+	// An optional regex pattern that a variable value must match before a package deployment can continue.
+	Pattern string `json:"pattern,omitempty"`
+	// Changes the handling of a variable to load contents differently.
+	Type VariableType `json:"type,omitempty" jsonschema:"enum=raw,enum=file"`
+}
+
+// InteractiveVariable is a variable that can be used to prompt a user for more information.
+type InteractiveVariable struct {
+	Variable `json:",inline"`
+	// A description of the variable to be used when prompting the user a value.
+	Description string `json:"description,omitempty"`
+	// The default value to use for the variable.
+	Default string `json:"default,omitempty"`
+	// Whether to prompt the user for input for this variable.
+	Prompt bool `json:"prompt,omitempty"`
+}
+
+// Constant is a value used to dynamically template resources or run in actions.
+type Constant struct {
+	// The name to be used for the constant.
+	Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"`
+	// The value to set for the constant during deploy.
+	Value string `json:"value"`
+	// A description of the constant.
+	Description string `json:"description,omitempty"`
+	// Whether to automatically indent the constant's value (if multiline) when templating.
+	AutoIndent bool `json:"autoIndent,omitempty"`
+	// An optional regex pattern that a constant value must match before a package can be created.
+	Pattern string `json:"pattern,omitempty"`
+}
+
+// ZarfComponent is the primary functional grouping of assets to deploy by Zarf.
+type ZarfComponent struct {
+	// The name of the component.
+	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
+	// Message to include during package deploy describing the purpose of this component.
+	Description string `json:"description,omitempty"`
+	// Determines the default Y/N state for installing this component on package deploy.
+	Default bool `json:"default,omitempty"`
+	// Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.
+	Optional *bool `json:"optional,omitempty"`
+	// Filter when this component is included in package creation or deployment.
+	Target ZarfComponentTarget `json:"target,omitempty"`
+	// Import a component from another Zarf component config.
+	Import ZarfComponentImport `json:"import,omitempty"`
+	// Zarf CLI services and infrastructure such as the registry, injector, and agent.
+	Services ZarfComponentServices `json:"services,omitempty"`
+	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
+	Manifests []ZarfManifest `json:"manifests,omitempty"`
+	// Helm charts to install during package deploy.
+	Charts []ZarfChart `json:"charts,omitempty"`
+	// Files or folders to place on disk during package deployment.
+	Files []ZarfFile `json:"files,omitempty"`
+	// List of OCI images to include in the package.
+	Images []ZarfImage `json:"images,omitempty"`
+	// List of tar archives of images to include in the package.
+	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
+	// List of git repositories to include in the package.
+	Repositories []string `json:"repositories,omitempty"`
+	// Custom commands to run at various stages of a package lifecycle.
+	Actions ZarfComponentActions `json:"actions,omitempty"`
+}
+
+// ZarfComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.
+type ZarfComponentTarget struct {
+	// Only deploy component to specified OS.
+	LocalOS string `json:"localOS,omitempty" jsonschema:"enum=linux,enum=darwin,enum=windows"`
+	// Only include component for the given package architecture.
+	Architecture string `json:"architecture,omitempty" jsonschema:"enum=amd64,enum=arm64"`
+	// Only include this component when a matching '--flavor' is specified on 'zarf package create'.
+	Flavor string `json:"flavor,omitempty"`
+}
+
+// ZarfComponentImport is a reference to an imported Zarf component config.
+type ZarfComponentImport struct {
+	// The path to the component config file to import.
+	Path string `json:"path,omitempty"`
+	// The URL to a Zarf component config to import via OCI.
+	URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"`
+}
+
+// ZarfComponentServices defines Zarf CLI services to enable for an init component.
+type ZarfComponentServices struct {
+	// Whether this component provides a registry.
+	IsRegistry bool `json:"isRegistry,omitempty"`
+	// Injector configuration for the component.
+	Injector *Injector `json:"injector,omitempty"`
+	// Whether this component provides an agent.
+	IsAgent bool `json:"isAgent,omitempty"`
+}
+
+// Injector defines the configuration for the Zarf injector.
+type Injector struct {
+	// Whether the injector is enabled.
+	Enabled bool `json:"enabled"`
+	// Values for the injector.
+	Values *InjectorValues `json:"values,omitempty"`
+}
+
+// InjectorValues defines configurable values for the Zarf injector.
+type InjectorValues struct {
+	// Tolerations for the injector pod.
+	Tolerations string `json:"tolerations,omitempty"`
+}
+
+// ZarfManifest defines raw manifests Zarf will deploy as a helm chart.
+type ZarfManifest struct {
+	// A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.
+	Name string `json:"name" jsonschema:"maxLength=40"`
+	// The namespace to deploy the manifests to.
+	Namespace string `json:"namespace,omitempty"`
+	// List of local K8s YAML files or remote URLs to deploy (in order).
+	Files []string `json:"files,omitempty"`
+	// Allow traversing directory above the current directory if needed for kustomization.
+	KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty"`
+	// List of local kustomization paths or remote URLs to include in the package.
+	Kustomizations []string `json:"kustomizations,omitempty"`
+	// Whether to wait for manifest resources to be ready before continuing. Defaults to true.
+	Wait *bool `json:"wait,omitempty"`
+	// Template enables go-template processing on these manifests during deploy.
+	Template *bool `json:"template,omitempty"`
+}
+
+// ZarfChart defines a helm chart to be deployed.
+type ZarfChart struct {
+	// The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repository.
+	Name string `json:"name"`
+	// The version of the chart. This field is removed from the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
+	version string
+	// The Helm repository where the chart is stored.
+	HelmRepository *HelmRepositorySource `json:"helmRepository,omitempty"`
+	// The Git repository where the chart is stored.
+	Git *GitSource `json:"git,omitempty"`
+	// The local path where the chart is stored.
+	Local *LocalSource `json:"local,omitempty"`
+	// The OCI registry where the chart is stored.
+	OCI *OCISource `json:"oci,omitempty"`
+	// The namespace to deploy the chart to.
+	Namespace string `json:"namespace,omitempty"`
+	// The name of the Helm release to create (defaults to the Zarf name of the chart).
+	ReleaseName string `json:"releaseName,omitempty"`
+	// Whether to wait for chart resources to be ready before continuing. Defaults to true.
+	Wait *bool `json:"wait,omitempty"`
+	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
+	ValuesFiles []string `json:"valuesFiles,omitempty"`
+	// List of value sources mapped to their Helm override targets.
+	Values []ZarfChartValue `json:"values,omitempty"`
+}
+
+// ZarfChartValue maps a values source path to a Helm chart target path.
+type ZarfChartValue struct {
+	// The source path for the value.
+	SourcePath string `json:"sourcePath"`
+	// The target path within the Helm chart values.
+	TargetPath string `json:"targetPath"`
+}
+
+// HelmRepositorySource represents a Helm chart stored in a Helm repository.
+type HelmRepositorySource struct {
+	// The name of a chart within a Helm repository.
+	Name string `json:"name,omitempty"`
+	// The URL of the chart repository where the Helm chart is stored.
+	URL string `json:"url"`
+	// The version of the chart in the Helm repository.
+	Version string `json:"version"`
+}
+
+// GitSource represents a Helm chart stored in a Git repository.
+type GitSource struct {
+	// The URL of the Git repository where the Helm chart is stored.
+	URL string `json:"url"`
+	// The subdirectory containing the chart within a Git repo.
+	Path string `json:"path,omitempty"`
+}
+
+// LocalSource represents a Helm chart stored locally.
+type LocalSource struct {
+	// The path to a local chart's folder or .tgz archive.
+	Path string `json:"path"`
+}
+
+// OCISource represents a Helm chart stored in an OCI registry.
+type OCISource struct {
+	// The URL of the OCI registry where the Helm chart is stored.
+	URL string `json:"url"`
+	// The version of the chart in the OCI registry.
+	Version string `json:"version"`
+}
+
+// ZarfFile defines a file to deploy.
+type ZarfFile struct {
+	// Local folder or file path or remote URL to pull into the package.
+	Source string `json:"source"`
+	// Optional SHA256 checksum of the file.
+	Shasum string `json:"shasum,omitempty"`
+	// The absolute or relative path where the file or folder should be copied to during package deploy.
+	Target string `json:"target"`
+	// Determines if the file should be made executable during package deploy.
+	Executable bool `json:"executable,omitempty"`
+	// List of symlinks to create during package deploy.
+	Symlinks []string `json:"symlinks,omitempty"`
+	// Local folder or file to be extracted from a 'source' archive.
+	ExtractPath string `json:"extractPath,omitempty"`
+	// Template enables go-template processing on this file during deploy.
+	Template *bool `json:"template,omitempty"`
+}
+
+// ZarfImage defines an OCI image to include in the package.
+type ZarfImage struct {
+	// The image reference.
+	Name string `json:"name"`
+	// The source to pull the image from. Defaults to "registry".
+	Source string `json:"source,omitempty" jsonschema:"enum=registry,enum=daemon"`
+}
+
+// ImageArchive defines a tar archive of images to include in the package.
+type ImageArchive struct {
+	// The path to the tar archive.
+	Path string `json:"path"`
+	// The list of images contained in the archive.
+	Images []string `json:"images"`
+}
+
+// ZarfComponentActions are ActionSets that map to different Zarf package operations.
+type ZarfComponentActions struct {
+	// Actions to run during package creation.
+	OnCreate ZarfComponentActionSet `json:"onCreate,omitempty"`
+	// Actions to run during package deployment.
+	OnDeploy ZarfComponentActionSet `json:"onDeploy,omitempty"`
+	// Actions to run during package removal.
+	OnRemove ZarfComponentActionSet `json:"onRemove,omitempty"`
+}
+
+// ZarfComponentActionSet is a set of actions to run during a Zarf package operation.
+type ZarfComponentActionSet struct {
+	// Default configuration for all actions in this set.
+	Defaults ZarfComponentActionDefaults `json:"defaults,omitempty"`
+	// Actions to run at the start of an operation.
+	Before []ZarfComponentAction `json:"before,omitempty"`
+	// Actions to run at the end of an operation.
+	After []ZarfComponentAction `json:"after,omitempty"`
+	// Actions to run if any operation in this set fails.
+	OnFailure []ZarfComponentAction `json:"onFailure,omitempty"`
+}
+
+// ZarfComponentActionDefaults sets the default configs for child actions.
+type ZarfComponentActionDefaults struct {
+	// Hide the output of commands during execution (default false).
+	Mute bool `json:"mute,omitempty"`
+	// Default timeout for commands.
+	Timeout *time.Duration `json:"timeout,omitempty"`
+	// Retry commands a given number of times if they fail (default 0).
+	Retries int `json:"retries,omitempty"`
+	// Working directory for commands (default CWD).
+	Dir string `json:"dir,omitempty"`
+	// Additional environment variables for commands.
+	Env []string `json:"env,omitempty"`
+	// Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems.
+	Shell Shell `json:"shell,omitempty"`
+}
+
+// ZarfComponentAction represents a single action to run during a Zarf package operation.
+type ZarfComponentAction struct {
+	// Hide the output of the command during package deployment (default false).
+	Mute *bool `json:"mute,omitempty"`
+	// Timeout for the command.
+	Timeout *time.Duration `json:"timeout,omitempty"`
+	// Retry the command if it fails up to a given number of times (default 0).
+	Retries int `json:"retries,omitempty"`
+	// The working directory to run the command in (default is CWD).
+	Dir *string `json:"dir,omitempty"`
+	// Additional environment variables to set for the command.
+	Env []string `json:"env,omitempty"`
+	// The command to run. Must specify either cmd or wait for the action to do anything.
+	Cmd string `json:"cmd,omitempty"`
+	// Indicates a preference for a shell for the provided cmd.
+	Shell *Shell `json:"shell,omitempty"`
+	// An array of variables to update with the output of the command.
+	SetVariables []Variable `json:"setVariables,omitempty"`
+	// An array of values to set with the output of the command.
+	SetValues []SetValue `json:"setValues,omitempty"`
+	// Description of the action to be displayed during package execution instead of the command.
+	Description string `json:"description,omitempty"`
+	// Wait for a condition to be met before continuing.
+	Wait *ZarfComponentActionWait `json:"wait,omitempty"`
+	// Template enables go-template processing on the cmd field.
+	Template *bool `json:"template,omitempty"`
+}
+
+// SetValueType declares the expected input back from the cmd, allowing structured data to be parsed.
+type SetValueType string
+
+const (
+	// SetValueYAML enables YAML parsing.
+	SetValueYAML SetValueType = "yaml"
+	// SetValueJSON enables JSON parsing.
+	SetValueJSON SetValueType = "json"
+	// SetValueString sets the raw value.
+	SetValueString SetValueType = "string"
+)
+
+// SetValue declares a value that can be set during a package deploy.
+type SetValue struct {
+	// Key represents which value to assign to.
+	Key string `json:"key,omitempty"`
+	// Value is the current value at the key.
+	Value any `json:"value,omitempty"`
+	// Type declares the kind of data being stored in the value.
+	Type SetValueType `json:"type,omitempty"`
+}
+
+// ZarfComponentActionWait specifies a condition to wait for before continuing.
+type ZarfComponentActionWait struct {
+	// Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified.
+	Cluster *ZarfComponentActionWaitCluster `json:"cluster,omitempty"`
+	// Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified.
+	Network *ZarfComponentActionWaitNetwork `json:"network,omitempty"`
+}
+
+// ZarfComponentActionWaitCluster specifies a cluster-level condition to wait for.
+type ZarfComponentActionWaitCluster struct {
+	// The kind of resource to wait for.
+	Kind string `json:"kind" jsonschema:"example=Pod,example=Deployment"`
+	// The name of the resource or selector to wait for.
+	Name string `json:"name" jsonschema:"example=podinfo,example=app=podinfo"`
+	// The namespace of the resource to wait for.
+	Namespace string `json:"namespace,omitempty"`
+	// The condition or jsonpath state to wait for; defaults to kstatus readiness checks.
+	Condition string `json:"condition,omitempty" jsonschema:"example=Available,'{.status.availableReplicas}'=23"`
+}
+
+// ZarfComponentActionWaitNetwork specifies a network-level condition to wait for.
+type ZarfComponentActionWaitNetwork struct {
+	// The protocol to wait for.
+	Protocol string `json:"protocol" jsonschema:"enum=tcp,enum=http,enum=https"`
+	// The address to wait for.
+	Address string `json:"address" jsonschema:"example=localhost:8080,example=1.1.1.1"`
+	// The HTTP status code to wait for if using http or https.
+	Code int `json:"code,omitempty" jsonschema:"example=200,example=404"`
+}
+
+// Shell represents the desired shell to use for a given command.
+type Shell struct {
+	// Windows shell preference.
+	Windows string `json:"windows,omitempty" jsonschema:"example=powershell,example=cmd,example=pwsh"`
+	// Linux shell preference.
+	Linux string `json:"linux,omitempty" jsonschema:"example=sh,example=bash,example=zsh"`
+	// Darwin (macOS) shell preference.
+	Darwin string `json:"darwin,omitempty" jsonschema:"example=sh,example=bash,example=zsh"`
+}

From 154f237a5cba39035a58d8de9a5887994d33f9c1 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 16:02:17 -0400
Subject: [PATCH 087/131] remove the word Zarf as a prefix for many objects

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  |  48 ++++++------
 0051-v1beta1-schema/package.go | 136 ++++++++++++++++-----------------
 2 files changed, 93 insertions(+), 91 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 75c848e..39ef28a 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -144,6 +144,8 @@ below is for the real nitty-gritty.
 
 Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. Until v1alpha is removed, if `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. `apiVersion` will be a required field in v1beta1 and all future schemas. 
 
+Type names will remove the prefix Zarf where applicable. For example, the type `ZarfMetadata` will become `Metadata`. This has no impact on the package yaml.
+
 Users will be able to upgrade their package definitions using `zarf dev upgrade-schema`, which writes the converted definition to stdout. 
 
 The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key.
@@ -172,7 +174,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
-- `.components.[x].images` will move from a list of strings to a list of objects. The ZarfImage object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append, to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
+- `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append, to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
 
 #### Renamed Fields
 
@@ -499,15 +501,15 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+The `Chart` object will be restructured to match the code block below. Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.git.URL`. This is consistent with the current Zarf behavior.
 
 Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
 
 ```go
-// ZarfChart defines a helm chart to be deployed.
-type ZarfChart struct {
+// Chart defines a helm chart to be deployed.
+type Chart struct {
 	// The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo.
 	Name string `json:"name"`
   // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
@@ -529,7 +531,7 @@ type ZarfChart struct {
 	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
   // [alpha] List of value sources mapped to their Helm override targets.
-	Values []ZarfChartValue `json:"values,omitempty"`
+	Values []ChartValue `json:"values,omitempty"`
 }
 
 // HelmRepositorySource represents a Helm chart stored in a Helm repository.
@@ -574,52 +576,52 @@ type ComponentConfig struct {
 	// The API version of the component config.
 	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
 	// The kind of component config.
-	Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
+	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
 	// Component metadata.
-	Metadata ZarfComponentMetadata `json:"metadata"`
+	Metadata ComponentMetadata `json:"metadata"`
   // Exactly one of Component or Variants must be set.
 	// A single component definition that applies in all contexts.
-	Component *Component `json:"component,omitempty" jsonschema:"oneof_required=component"`
+	Component *ImportableComponent `json:"component,omitempty" jsonschema:"oneof_required=component"`
 	// A list of component variants, each with a distinct .target filter. Use this when the
 	// component has different definitions for different flavors, OSes, or architectures.
 	Variants []Variant `json:"variants,omitempty" jsonschema:"oneof_required=variants"`
 	// Values imports Zarf values files for templating and overriding Helm values.
-	Values ZarfValues `json:"values,omitempty"`
+	Values Values `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.
 	PublishData ComponentPublishData `json:"publishData,omitempty"`
 }
 
-// Component is a reduced component definition used in component configs.
-type Component struct {
+// ImportableComponent is a reduced component definition used in component configs.
+type ImportableComponent struct {
 	// Import a component from another Zarf component config.
-	Import ZarfComponentImport `json:"import,omitempty"`
+	Import ComponentImport `json:"import,omitempty"`
 	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
-	Manifests []ZarfManifest `json:"manifests,omitempty"`
+	Manifests []Manifest `json:"manifests,omitempty"`
 	// Helm charts to install during package deploy.
-	Charts []ZarfChart `json:"charts,omitempty"`
+	Charts []Chart `json:"charts,omitempty"`
 	// Files or folders to place on disk during package deployment.
-	Files []ZarfFile `json:"files,omitempty"`
+	Files []File `json:"files,omitempty"`
 	// List of OCI images to include in the package.
-	Images []ZarfImage `json:"images,omitempty"`
+	Images []Image `json:"images,omitempty"`
 	// List of Tar files of images to bring into the package.
 	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
 	// List of git repositories to include in the package.
 	Repositories []string `json:"repositories,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
-	Actions ZarfComponentActions `json:"actions,omitempty"`
+	Actions ComponentActions `json:"actions,omitempty"`
   // Zarf CLI services and infrastructure such as the registry, injector, and agent.
-  Services ZarfComponentServices `json:"services,omitempty"`
+  Services ComponentServices `json:"services,omitempty"`
 }
 
 // Variant is a component definition with a required filter for when it applies.
 type Variant struct {
-	Component
+	ImportableComponent
 	// Filter when this variant is included in package creation or deployment.
-	Target ZarfComponentTarget `json:"target"`
+	Target ComponentTarget `json:"target"`
 }
 
-// ZarfComponentMetadata holds metadata about a component config.
-type ZarfComponentMetadata struct {
+// ComponentMetadata holds metadata about a component config.
+type ComponentMetadata struct {
 	// Name to identify this component config.
 	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
 	// Additional information about this component config.
@@ -646,7 +648,7 @@ type ComponentPublishData struct {
 The schema for Zarf Services:
 
 ```go
-type ZarfComponentServices struct {
+type ComponentServices struct {
   IsRegistry bool       `json:"isRegistry,omitempty"`
   Injector   *Injector  `json:"injector,omitempty"`
   IsAgent    bool       `json:"isAgent,omitempty"`
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index a6a4483..2d9a980 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -18,42 +18,42 @@ const (
 	FileVariableType VariableType = "file"
 )
 
-// ZarfPackageKind is an enum of the different kinds of Zarf packages.
-type ZarfPackageKind string
+// PackageKind is an enum of the different kinds of Zarf packages.
+type PackageKind string
 
 const (
 	// ZarfInitConfig is the kind of Zarf package used during `zarf init`.
-	ZarfInitConfig ZarfPackageKind = "ZarfInitConfig"
+	ZarfInitConfig PackageKind = "ZarfInitConfig"
 	// ZarfPackageConfig is the default kind of Zarf package.
-	ZarfPackageConfig ZarfPackageKind = "ZarfPackageConfig"
+	ZarfPackageConfig PackageKind = "ZarfPackageConfig"
 	// APIVersion is the api version of this package.
 	APIVersion string = "zarf.dev/v1beta1"
 )
 
-// ZarfPackage is the top-level structure of a Zarf package definition.
-type ZarfPackage struct {
+// Package is the top-level structure of a Zarf package definition.
+type Package struct {
 	// The API version of the Zarf package.
 	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
 	// The kind of Zarf package.
-	Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"`
+	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"`
 	// Package metadata.
-	Metadata ZarfMetadata `json:"metadata,omitempty"`
+	Metadata Metadata `json:"metadata,omitempty"`
 	// Zarf-generated package build data.
-	Build ZarfBuildData `json:"build,omitempty"`
+	Build BuildData `json:"build,omitempty"`
 	// List of components to deploy in this package.
-	Components []ZarfComponent `json:"components" jsonschema:"minItems=1"`
+	Components []Component `json:"components" jsonschema:"minItems=1"`
 	// Constant template values applied on deploy.
 	Constants []Constant `json:"constants,omitempty"`
 	// Variable template values applied on deploy.
 	Variables []InteractiveVariable `json:"variables,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
-	Values ZarfValues `json:"values,omitempty"`
+	Values Values `json:"values,omitempty"`
 	// Documentation files included in the package.
 	Documentation map[string]string `json:"documentation,omitempty"`
 }
 
-// ZarfMetadata holds information about the package.
-type ZarfMetadata struct {
+// Metadata holds information about the package.
+type Metadata struct {
 	// Name to identify this Zarf package.
 	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
 	// Additional information about this Zarf package.
@@ -70,8 +70,8 @@ type ZarfMetadata struct {
 	AllowNamespaceOverride *bool `json:"allowNamespaceOverride,omitempty"`
 }
 
-// ZarfBuildData is written during package create to track details of the created package.
-type ZarfBuildData struct {
+// BuildData is written during package create to track details of the created package.
+type BuildData struct {
 	// The machine name that created this package.
 	Terminal string `json:"terminal,omitempty"`
 	// The username who created this package.
@@ -104,8 +104,8 @@ type VersionRequirement struct {
 	Reason string `json:"reason"`
 }
 
-// ZarfValues defines values files and schema for templating and overriding Helm values.
-type ZarfValues struct {
+// Values defines values files and schema for templating and overriding Helm values.
+type Values struct {
 	// List of values file paths to include.
 	Files []string `json:"files,omitempty"`
 	// Path to a JSON schema file for validating values.
@@ -151,8 +151,8 @@ type Constant struct {
 	Pattern string `json:"pattern,omitempty"`
 }
 
-// ZarfComponent is the primary functional grouping of assets to deploy by Zarf.
-type ZarfComponent struct {
+// Component is the primary functional grouping of assets to deploy by Zarf.
+type Component struct {
 	// The name of the component.
 	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
 	// Message to include during package deploy describing the purpose of this component.
@@ -162,29 +162,29 @@ type ZarfComponent struct {
 	// Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.
 	Optional *bool `json:"optional,omitempty"`
 	// Filter when this component is included in package creation or deployment.
-	Target ZarfComponentTarget `json:"target,omitempty"`
+	Target ComponentTarget `json:"target,omitempty"`
 	// Import a component from another Zarf component config.
-	Import ZarfComponentImport `json:"import,omitempty"`
+	Import ComponentImport `json:"import,omitempty"`
 	// Zarf CLI services and infrastructure such as the registry, injector, and agent.
-	Services ZarfComponentServices `json:"services,omitempty"`
+	Services ComponentServices `json:"services,omitempty"`
 	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
-	Manifests []ZarfManifest `json:"manifests,omitempty"`
+	Manifests []Manifest `json:"manifests,omitempty"`
 	// Helm charts to install during package deploy.
-	Charts []ZarfChart `json:"charts,omitempty"`
+	Charts []Chart `json:"charts,omitempty"`
 	// Files or folders to place on disk during package deployment.
-	Files []ZarfFile `json:"files,omitempty"`
+	Files []File `json:"files,omitempty"`
 	// List of OCI images to include in the package.
-	Images []ZarfImage `json:"images,omitempty"`
+	Images []Image `json:"images,omitempty"`
 	// List of tar archives of images to include in the package.
 	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
 	// List of git repositories to include in the package.
 	Repositories []string `json:"repositories,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
-	Actions ZarfComponentActions `json:"actions,omitempty"`
+	Actions ComponentActions `json:"actions,omitempty"`
 }
 
-// ZarfComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.
-type ZarfComponentTarget struct {
+// ComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.
+type ComponentTarget struct {
 	// Only deploy component to specified OS.
 	LocalOS string `json:"localOS,omitempty" jsonschema:"enum=linux,enum=darwin,enum=windows"`
 	// Only include component for the given package architecture.
@@ -193,16 +193,16 @@ type ZarfComponentTarget struct {
 	Flavor string `json:"flavor,omitempty"`
 }
 
-// ZarfComponentImport is a reference to an imported Zarf component config.
-type ZarfComponentImport struct {
+// ComponentImport is a reference to an imported Zarf component config.
+type ComponentImport struct {
 	// The path to the component config file to import.
 	Path string `json:"path,omitempty"`
 	// The URL to a Zarf component config to import via OCI.
 	URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"`
 }
 
-// ZarfComponentServices defines Zarf CLI services to enable for an init component.
-type ZarfComponentServices struct {
+// ComponentServices defines Zarf CLI services to enable for an init component.
+type ComponentServices struct {
 	// Whether this component provides a registry.
 	IsRegistry bool `json:"isRegistry,omitempty"`
 	// Injector configuration for the component.
@@ -225,8 +225,8 @@ type InjectorValues struct {
 	Tolerations string `json:"tolerations,omitempty"`
 }
 
-// ZarfManifest defines raw manifests Zarf will deploy as a helm chart.
-type ZarfManifest struct {
+// Manifest defines raw manifests Zarf will deploy as a helm chart.
+type Manifest struct {
 	// A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.
 	Name string `json:"name" jsonschema:"maxLength=40"`
 	// The namespace to deploy the manifests to.
@@ -243,8 +243,8 @@ type ZarfManifest struct {
 	Template *bool `json:"template,omitempty"`
 }
 
-// ZarfChart defines a helm chart to be deployed.
-type ZarfChart struct {
+// Chart defines a helm chart to be deployed.
+type Chart struct {
 	// The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repository.
 	Name string `json:"name"`
 	// The version of the chart. This field is removed from the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
@@ -266,11 +266,11 @@ type ZarfChart struct {
 	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
 	// List of value sources mapped to their Helm override targets.
-	Values []ZarfChartValue `json:"values,omitempty"`
+	Values []ChartValue `json:"values,omitempty"`
 }
 
-// ZarfChartValue maps a values source path to a Helm chart target path.
-type ZarfChartValue struct {
+// ChartValue maps a values source path to a Helm chart target path.
+type ChartValue struct {
 	// The source path for the value.
 	SourcePath string `json:"sourcePath"`
 	// The target path within the Helm chart values.
@@ -309,8 +309,8 @@ type OCISource struct {
 	Version string `json:"version"`
 }
 
-// ZarfFile defines a file to deploy.
-type ZarfFile struct {
+// File defines a file to deploy.
+type File struct {
 	// Local folder or file path or remote URL to pull into the package.
 	Source string `json:"source"`
 	// Optional SHA256 checksum of the file.
@@ -327,8 +327,8 @@ type ZarfFile struct {
 	Template *bool `json:"template,omitempty"`
 }
 
-// ZarfImage defines an OCI image to include in the package.
-type ZarfImage struct {
+// Image defines an OCI image to include in the package.
+type Image struct {
 	// The image reference.
 	Name string `json:"name"`
 	// The source to pull the image from. Defaults to "registry".
@@ -343,30 +343,30 @@ type ImageArchive struct {
 	Images []string `json:"images"`
 }
 
-// ZarfComponentActions are ActionSets that map to different Zarf package operations.
-type ZarfComponentActions struct {
+// ComponentActions are ActionSets that map to different Zarf package operations.
+type ComponentActions struct {
 	// Actions to run during package creation.
-	OnCreate ZarfComponentActionSet `json:"onCreate,omitempty"`
+	OnCreate ComponentActionSet `json:"onCreate,omitempty"`
 	// Actions to run during package deployment.
-	OnDeploy ZarfComponentActionSet `json:"onDeploy,omitempty"`
+	OnDeploy ComponentActionSet `json:"onDeploy,omitempty"`
 	// Actions to run during package removal.
-	OnRemove ZarfComponentActionSet `json:"onRemove,omitempty"`
+	OnRemove ComponentActionSet `json:"onRemove,omitempty"`
 }
 
-// ZarfComponentActionSet is a set of actions to run during a Zarf package operation.
-type ZarfComponentActionSet struct {
+// ComponentActionSet is a set of actions to run during a Zarf package operation.
+type ComponentActionSet struct {
 	// Default configuration for all actions in this set.
-	Defaults ZarfComponentActionDefaults `json:"defaults,omitempty"`
+	Defaults ComponentActionDefaults `json:"defaults,omitempty"`
 	// Actions to run at the start of an operation.
-	Before []ZarfComponentAction `json:"before,omitempty"`
+	Before []ComponentAction `json:"before,omitempty"`
 	// Actions to run at the end of an operation.
-	After []ZarfComponentAction `json:"after,omitempty"`
+	After []ComponentAction `json:"after,omitempty"`
 	// Actions to run if any operation in this set fails.
-	OnFailure []ZarfComponentAction `json:"onFailure,omitempty"`
+	OnFailure []ComponentAction `json:"onFailure,omitempty"`
 }
 
-// ZarfComponentActionDefaults sets the default configs for child actions.
-type ZarfComponentActionDefaults struct {
+// ComponentActionDefaults sets the default configs for child actions.
+type ComponentActionDefaults struct {
 	// Hide the output of commands during execution (default false).
 	Mute bool `json:"mute,omitempty"`
 	// Default timeout for commands.
@@ -381,8 +381,8 @@ type ZarfComponentActionDefaults struct {
 	Shell Shell `json:"shell,omitempty"`
 }
 
-// ZarfComponentAction represents a single action to run during a Zarf package operation.
-type ZarfComponentAction struct {
+// ComponentAction represents a single action to run during a Zarf package operation.
+type ComponentAction struct {
 	// Hide the output of the command during package deployment (default false).
 	Mute *bool `json:"mute,omitempty"`
 	// Timeout for the command.
@@ -404,7 +404,7 @@ type ZarfComponentAction struct {
 	// Description of the action to be displayed during package execution instead of the command.
 	Description string `json:"description,omitempty"`
 	// Wait for a condition to be met before continuing.
-	Wait *ZarfComponentActionWait `json:"wait,omitempty"`
+	Wait *ComponentActionWait `json:"wait,omitempty"`
 	// Template enables go-template processing on the cmd field.
 	Template *bool `json:"template,omitempty"`
 }
@@ -431,16 +431,16 @@ type SetValue struct {
 	Type SetValueType `json:"type,omitempty"`
 }
 
-// ZarfComponentActionWait specifies a condition to wait for before continuing.
-type ZarfComponentActionWait struct {
+// ComponentActionWait specifies a condition to wait for before continuing.
+type ComponentActionWait struct {
 	// Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified.
-	Cluster *ZarfComponentActionWaitCluster `json:"cluster,omitempty"`
+	Cluster *ComponentActionWaitCluster `json:"cluster,omitempty"`
 	// Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified.
-	Network *ZarfComponentActionWaitNetwork `json:"network,omitempty"`
+	Network *ComponentActionWaitNetwork `json:"network,omitempty"`
 }
 
-// ZarfComponentActionWaitCluster specifies a cluster-level condition to wait for.
-type ZarfComponentActionWaitCluster struct {
+// ComponentActionWaitCluster specifies a cluster-level condition to wait for.
+type ComponentActionWaitCluster struct {
 	// The kind of resource to wait for.
 	Kind string `json:"kind" jsonschema:"example=Pod,example=Deployment"`
 	// The name of the resource or selector to wait for.
@@ -451,8 +451,8 @@ type ZarfComponentActionWaitCluster struct {
 	Condition string `json:"condition,omitempty" jsonschema:"example=Available,'{.status.availableReplicas}'=23"`
 }
 
-// ZarfComponentActionWaitNetwork specifies a network-level condition to wait for.
-type ZarfComponentActionWaitNetwork struct {
+// ComponentActionWaitNetwork specifies a network-level condition to wait for.
+type ComponentActionWaitNetwork struct {
 	// The protocol to wait for.
 	Protocol string `json:"protocol" jsonschema:"enum=tcp,enum=http,enum=https"`
 	// The address to wait for.

From 36ec65644358fcc548a2aec5f3998cd6fef545c2 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 16:07:49 -0400
Subject: [PATCH 088/131] show full go objects

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md          | 157 +------------------------
 0051-v1beta1-schema/componentConfig.go |  74 ++++++++++++
 2 files changed, 77 insertions(+), 154 deletions(-)
 create mode 100644 0051-v1beta1-schema/componentConfig.go

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 39ef28a..619bbae 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -204,7 +204,7 @@ In the v1alpha1 schema, Zarf looks at init component names to determine when to
 
 A new "services" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.services.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent services don't allow setting specific values, as those services already have Helm charts. There will be validation that ensures Services are only used in packages that are `Kind: ZarfInitConfig`. There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
 
-View the full schema in [Zarf Services Schema](#zarf-services-schema). 
+View the full schema in [package.go](package.go#L204-L226). 
 
 ```yaml
 - name: zarf-seed-registry
@@ -507,162 +507,11 @@ During conversion, Zarf will detect the method of consuming the chart and create
 
 Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
 
-```go
-// Chart defines a helm chart to be deployed.
-type Chart struct {
-	// The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo.
-	Name string `json:"name"`
-  // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1.
-  version string
-	// The Helm repository where the chart is stored
-	HelmRepository *HelmRepositorySource `json:"helmRepository,omitempty"`
-	// The Git repository where the chart is stored
-	Git *GitSource `json:"git,omitempty"`
-	// The local path where the chart is stored
-	Local *LocalSource `json:"local,omitempty"`
-	// The OCI registry where the chart is stored
-	OCI *OCISource `json:"oci,omitempty"`
-	// The namespace to deploy the chart to.
-	Namespace string `json:"namespace,omitempty"`
-	// The name of the Helm release to create (defaults to the Zarf name of the chart).
-	ReleaseName string `json:"releaseName,omitempty"`
-	// Whether to wait for chart resources to be ready before continuing.
-	Wait *bool `json:"wait,omitempty"`
-	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
-	ValuesFiles []string `json:"valuesFiles,omitempty"`
-  // [alpha] List of value sources mapped to their Helm override targets.
-	Values []ChartValue `json:"values,omitempty"`
-}
-
-// HelmRepositorySource represents a Helm chart stored in a Helm repository.
-type HelmRepositorySource struct {
-	// The name of a chart within a Helm repository.
-	Name string `json:"name,omitempty"`
-	// The URL of the chart repository where the Helm chart is stored.
-	URL string `json:"url"`
-  // The version of the chart in the Helm repository.
-	Version string `json:"version"`
-}
-
-// GitSource represents a Helm chart stored in a Git repository.
-type GitSource struct {
-	// The URL of the Git repository where the Helm chart is stored.
-	URL string `json:"url"`
-	// The subdirectory containing the chart within a Git repo.
-	Path string `json:"path,omitempty"`
-}
-
-// LocalSource represents a Helm chart stored locally.
-type LocalSource struct {
-	// The path to a local chart's folder or .tgz archive.
-	Path string `json:"path"`
-}
-
-// OCISource represents a Helm chart stored in an OCI registry.
-type OCISource struct {
-	// The URL of the OCI registry where the Helm chart is stored.
-	URL     string `json:"url"`
-	Version string `json:"version"`
-}
-```
+View the restructured `Chart` schema and its source sub-objects in [package.go](package.go#L246-L310).
 
 ### Zarf Component Config Schema
 
-The schema for the Zarf component config will look like so:
-
-```go
-// ComponentConfig is the top-level structure of a Zarf component config file.
-type ComponentConfig struct {
-	// The API version of the component config.
-	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
-	// The kind of component config.
-	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
-	// Component metadata.
-	Metadata ComponentMetadata `json:"metadata"`
-  // Exactly one of Component or Variants must be set.
-	// A single component definition that applies in all contexts.
-	Component *ImportableComponent `json:"component,omitempty" jsonschema:"oneof_required=component"`
-	// A list of component variants, each with a distinct .target filter. Use this when the
-	// component has different definitions for different flavors, OSes, or architectures.
-	Variants []Variant `json:"variants,omitempty" jsonschema:"oneof_required=variants"`
-	// Values imports Zarf values files for templating and overriding Helm values.
-	Values Values `json:"values,omitempty"`
-	// Zarf-generated publish data for the component config.
-	PublishData ComponentPublishData `json:"publishData,omitempty"`
-}
-
-// ImportableComponent is a reduced component definition used in component configs.
-type ImportableComponent struct {
-	// Import a component from another Zarf component config.
-	Import ComponentImport `json:"import,omitempty"`
-	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
-	Manifests []Manifest `json:"manifests,omitempty"`
-	// Helm charts to install during package deploy.
-	Charts []Chart `json:"charts,omitempty"`
-	// Files or folders to place on disk during package deployment.
-	Files []File `json:"files,omitempty"`
-	// List of OCI images to include in the package.
-	Images []Image `json:"images,omitempty"`
-	// List of Tar files of images to bring into the package.
-	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
-	// List of git repositories to include in the package.
-	Repositories []string `json:"repositories,omitempty"`
-	// Custom commands to run at various stages of a package lifecycle.
-	Actions ComponentActions `json:"actions,omitempty"`
-  // Zarf CLI services and infrastructure such as the registry, injector, and agent.
-  Services ComponentServices `json:"services,omitempty"`
-}
-
-// Variant is a component definition with a required filter for when it applies.
-type Variant struct {
-	ImportableComponent
-	// Filter when this variant is included in package creation or deployment.
-	Target ComponentTarget `json:"target"`
-}
-
-// ComponentMetadata holds metadata about a component config.
-type ComponentMetadata struct {
-	// Name to identify this component config.
-	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
-	// Additional information about this component config.
-	Description string `json:"description,omitempty"`
-	// Generic string to track the component config version.
-	Version string `json:"version,omitempty"`
-	// Annotations contains arbitrary metadata about the component config.
-	Annotations map[string]string `json:"annotations,omitempty"`
-}
-
-// ComponentPublishData is written during publish to track details of the component config.
-type ComponentPublishData struct {
-	// The version of Zarf used to build this component config.
-	ZarfVersion string `json:"zarfVersion"`
-	// Any migrations that have been run on this component config.
-	Migrations []string `json:"migrations,omitempty"`
-	// Requirements for specific package operations.
-	VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"`
-}
-```
-
-### Zarf Services Schema
-
-The schema for Zarf Services:
-
-```go
-type ComponentServices struct {
-  IsRegistry bool       `json:"isRegistry,omitempty"`
-  Injector   *Injector  `json:"injector,omitempty"`
-  IsAgent    bool       `json:"isAgent,omitempty"`
-}
-
-type Injector struct {
-  Enabled bool             `json:"enabled"`
-  Values  *InjectorValues  `json:"values,omitempty"`
-}
-
-type InjectorValues struct {
-  Tolerations string `json:"tolerations,omitempty"`
-}
-```
+View the schema for the Zarf component config in [componentConfig.go](componentConfig.go).
 
 ### Test Plan
 
diff --git a/0051-v1beta1-schema/componentConfig.go b/0051-v1beta1-schema/componentConfig.go
new file mode 100644
index 0000000..8ae1588
--- /dev/null
+++ b/0051-v1beta1-schema/componentConfig.go
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2021-Present The Zarf Authors
+
+package v1beta1
+
+// ComponentConfig is the top-level structure of a Zarf component config file.
+type ComponentConfig struct {
+	// The API version of the component config.
+	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
+	// The kind of component config.
+	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
+	// Component metadata.
+	Metadata ComponentMetadata `json:"metadata"`
+	// A single component definition that applies in all contexts. Exactly one of Component or Variants must be set.
+	Component *ImportableComponent `json:"component,omitempty" jsonschema:"oneof_required=component"`
+	// A list of component variants, each with a distinct .target filter. Use this when the
+	// component has different definitions for different flavors, OSes, or architectures.
+	Variants []Variant `json:"variants,omitempty" jsonschema:"oneof_required=variants"`
+	// Values imports Zarf values files for templating and overriding Helm values.
+	Values Values `json:"values,omitempty"`
+	// Zarf-generated publish data for the component config.
+	PublishData ComponentPublishData `json:"publishData,omitempty"`
+}
+
+// ImportableComponent is a reduced component definition used in component configs.
+type ImportableComponent struct {
+	// Import a component from another Zarf component config.
+	Import ComponentImport `json:"import,omitempty"`
+	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
+	Manifests []Manifest `json:"manifests,omitempty"`
+	// Helm charts to install during package deploy.
+	Charts []Chart `json:"charts,omitempty"`
+	// Files or folders to place on disk during package deployment.
+	Files []File `json:"files,omitempty"`
+	// List of OCI images to include in the package.
+	Images []Image `json:"images,omitempty"`
+	// List of tar archives of images to include in the package.
+	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
+	// List of git repositories to include in the package.
+	Repositories []string `json:"repositories,omitempty"`
+	// Custom commands to run at various stages of a package lifecycle.
+	Actions ComponentActions `json:"actions,omitempty"`
+	// Zarf CLI services and infrastructure such as the registry, injector, and agent.
+	Services ComponentServices `json:"services,omitempty"`
+}
+
+// Variant is a component definition with a required filter for when it applies.
+type Variant struct {
+	ImportableComponent
+	// Filter when this variant is included in package creation or deployment.
+	Target ComponentTarget `json:"target"`
+}
+
+// ComponentMetadata holds metadata about a component config.
+type ComponentMetadata struct {
+	// Name to identify this component config.
+	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
+	// Additional information about this component config.
+	Description string `json:"description,omitempty"`
+	// Generic string to track the component config version.
+	Version string `json:"version,omitempty"`
+	// Annotations contains arbitrary metadata about the component config.
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+
+// ComponentPublishData is written during publish to track details of the component config.
+type ComponentPublishData struct {
+	// The version of Zarf used to build this component config.
+	ZarfVersion string `json:"zarfVersion"`
+	// Any migrations that have been run on this component config.
+	Migrations []string `json:"migrations,omitempty"`
+	// Requirements for specific package operations.
+	VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"`
+}

From 69474c98131f1741d4af91d9169aef7b6551aee3 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 22 Apr 2026 16:14:50 -0400
Subject: [PATCH 089/131] correct mistakes

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 10 ++++------
 0051-v1beta1-schema/package.go |  2 ++
 0051-v1beta1-schema/zarf.yaml  | 13 ++++++-------
 3 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 619bbae..61c3435 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -161,7 +161,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
 - `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
 - `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig).
-- `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are plans to use it currently.
+- `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are no plans to use it currently.
 
 #### Replaced / Restructured Fields
 
@@ -171,7 +171,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`. Since `.cluster.distro` will be removed, the `.cluster` parent field will be deleted. 
-- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendors` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
+- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendor` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
 - `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append, to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
@@ -501,14 +501,12 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The `Chart` object will be restructured to match the code block below. Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245).
+The `Chart` object will be restructured as seen in [package.go](package.go#L246-L312). Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/zarf-dev/zarf/issues/2245).
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.git.URL`. This is consistent with the current Zarf behavior.
 
 Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
 
-View the restructured `Chart` schema and its source sub-objects in [package.go](package.go#L246-L310).
-
 ### Zarf Component Config Schema
 
 View the schema for the Zarf component config in [componentConfig.go](componentConfig.go).
@@ -628,4 +626,4 @@ information to express the idea and why it was not acceptable.
 
 ### Component Import Schema
 
-Another possibility for the [component imports schema](#component-import-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
\ No newline at end of file
+Another possibility for the [component config schema](#zarf-component-config-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
\ No newline at end of file
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 2d9a980..426d412 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -267,6 +267,8 @@ type Chart struct {
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
 	// List of value sources mapped to their Helm override targets.
 	Values []ChartValue `json:"values,omitempty"`
+	// Whether to validate the chart's values against its JSON schema. Defaults to true.
+	SchemaValidation *bool `json:"schemaValidation,omitempty"`
 }
 
 // ChartValue maps a values source path to a Helm chart target path.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 549da00..08dff80 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -6,7 +6,7 @@ metadata:
   version: v1.0.0
   uncompressed: false
   architecture: amd64
-  annotations: # All of these are v0 fields that will be deprecated in favor of a choose your own adventure label map
+  annotations: # All of these are v1alpha1 fields that will be deprecated in favor of a choose your own adventure label map
     authors: cool-kidz
     documentation: https://my-package-documentation.com
     source: https://my-git-server/my-package
@@ -43,13 +43,12 @@ components:
   optional: false # Component is required (default behavior)
   target:
     localOS: darwin
-    cluster:
-      architecture: amd64
+    architecture: amd64
     flavor: a-flavor # this will only be used when there are multiple components
   import:
     path: ABCD # Only path or URL will be used, not both
     url: oci://
-  features:
+  services:
     isRegistry: false
     injector:
       enabled: true
@@ -77,12 +76,12 @@ components:
     - sourcePath: ".app.name"
       targetPath: ".appName"
     schemaValidation: true
-    helmRepository: # Only one of helmRepository, git, oci, url, or local is allowed
+    helmRepository: # Only one of helmRepository, git, oci, or local is allowed
       url: https://stefanprodan.github.io/podinfo
       name: podinfo # replaces repoName since it's only applicable in this situation
       version: 6.4.0
     git:
-      url: https://stefanprodan.github.io/podinfo
+      url: https://github.com/stefanprodan/podinfo.git@6.4.0
       path: charts/podinfo
     oci:
       url: oci://ghcr.io/stefanprodan/charts/podinfo
@@ -99,7 +98,7 @@ components:
     extractPath: /path/to/extract
     template: false # Disable go-template processing for this file
   images:
-    - name: podinfo@v1
+    - name: podinfo:v1
       source: "registry" # optional - registry is the default value
   imageArchives:
   - path: podinfo.tar

From f20055a68fad8e0e786e5c9cb9cc4ee9ccea0641 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 29 Apr 2026 11:30:57 -0400
Subject: [PATCH 090/131] wait back to nowait

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md          | 1 -
 0051-v1beta1-schema/componentConfig.go | 4 ++++
 0051-v1beta1-schema/package.go         | 8 ++++----
 0051-v1beta1-schema/zarf.yaml          | 4 ++--
 4 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 61c3435..1ce0507 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -182,7 +182,6 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
-- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 - `.components.[x].only` will be renamed to `.components.[x].target`.
diff --git a/0051-v1beta1-schema/componentConfig.go b/0051-v1beta1-schema/componentConfig.go
index 8ae1588..067d844 100644
--- a/0051-v1beta1-schema/componentConfig.go
+++ b/0051-v1beta1-schema/componentConfig.go
@@ -16,6 +16,10 @@ type ComponentConfig struct {
 	// A list of component variants, each with a distinct .target filter. Use this when the
 	// component has different definitions for different flavors, OSes, or architectures.
 	Variants []Variant `json:"variants,omitempty" jsonschema:"oneof_required=variants"`
+	// Constant template values applied on deploy.
+	Constants []Constant `json:"constants,omitempty"`
+	// Variable template values applied on deploy.
+	Variables []InteractiveVariable `json:"variables,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values Values `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 426d412..e984da6 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -237,8 +237,8 @@ type Manifest struct {
 	KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty"`
 	// List of local kustomization paths or remote URLs to include in the package.
 	Kustomizations []string `json:"kustomizations,omitempty"`
-	// Whether to wait for manifest resources to be ready before continuing. Defaults to true.
-	Wait *bool `json:"wait,omitempty"`
+	// Whether to not wait for manifest resources to be ready before continuing.
+	NoWait *bool `json:"noWait,omitempty"`
 	// Template enables go-template processing on these manifests during deploy.
 	Template *bool `json:"template,omitempty"`
 }
@@ -261,8 +261,8 @@ type Chart struct {
 	Namespace string `json:"namespace,omitempty"`
 	// The name of the Helm release to create (defaults to the Zarf name of the chart).
 	ReleaseName string `json:"releaseName,omitempty"`
-	// Whether to wait for chart resources to be ready before continuing. Defaults to true.
-	Wait *bool `json:"wait,omitempty"`
+	// Whether to not wait for chart resources to be ready before continuing.
+	NoWait *bool `json:"noWait,omitempty"`
 	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
 	// List of value sources mapped to their Helm override targets.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 08dff80..acd683d 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -63,13 +63,13 @@ components:
     kustomizeAllowAnyDirectory: false
     kustomizations:
     - a-kustomization.yaml
-    wait: false
+    noWait: true
     template: true # Enable go-template processing
   charts:
   - name: chart
     namespace: chart-ns
     releaseName: chart-release
-    wait: true
+    noWait: false
     valuesFiles:
     - values.yaml
     values:

From 02b27b98ac238b022ad1dc60924d6bb9244bba9a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 29 Apr 2026 11:40:17 -0400
Subject: [PATCH 091/131] revert change to maxTotalSeconds

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  |  5 ++---
 0051-v1beta1-schema/package.go | 12 ++++--------
 0051-v1beta1-schema/zarf.yaml  | 24 ++++++++++++------------
 3 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 1ce0507..507d308 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -183,7 +183,6 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
-- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration).
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`
 
@@ -203,7 +202,7 @@ In the v1alpha1 schema, Zarf looks at init component names to determine when to
 
 A new "services" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.services.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent services don't allow setting specific values, as those services already have Helm charts. There will be validation that ensures Services are only used in packages that are `Kind: ZarfInitConfig`. There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
 
-View the full schema in [package.go](package.go#L204-L226). 
+View the full schema in [package.go](package.go#L200-L222). 
 
 ```yaml
 - name: zarf-seed-registry
@@ -500,7 +499,7 @@ proposal will be implemented, this is the place to discuss that.
 
 ### Zarf Helm Chart Changes
 
-The `Chart` object will be restructured as seen in [package.go](package.go#L246-L312). Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/zarf-dev/zarf/issues/2245).
+The `Chart` object will be restructured as seen in [package.go](package.go#L242-L308). Exactly one of sub-objects `helmRepository`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/zarf-dev/zarf/issues/2245).
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.git.URL`. This is consistent with the current Zarf behavior.
 
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index e984da6..48200af 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -4,10 +4,6 @@
 // Package v1beta1 holds the definition of the v1beta1 Zarf Package.
 package v1beta1
 
-import (
-	"time"
-)
-
 // VariableType represents a type of a Zarf package variable.
 type VariableType string
 
@@ -371,8 +367,8 @@ type ComponentActionSet struct {
 type ComponentActionDefaults struct {
 	// Hide the output of commands during execution (default false).
 	Mute bool `json:"mute,omitempty"`
-	// Default timeout for commands.
-	Timeout *time.Duration `json:"timeout,omitempty"`
+	// Default timeout in seconds for commands (default to 0, no timeout).
+	MaxTotalSeconds int `json:"maxTotalSeconds,omitempty"`
 	// Retry commands a given number of times if they fail (default 0).
 	Retries int `json:"retries,omitempty"`
 	// Working directory for commands (default CWD).
@@ -387,8 +383,8 @@ type ComponentActionDefaults struct {
 type ComponentAction struct {
 	// Hide the output of the command during package deployment (default false).
 	Mute *bool `json:"mute,omitempty"`
-	// Timeout for the command.
-	Timeout *time.Duration `json:"timeout,omitempty"`
+	// Timeout in seconds for the command (default to 0, no timeout for cmd actions and 300, 5 minutes for wait actions).
+	MaxTotalSeconds *int `json:"maxTotalSeconds,omitempty"`
 	// Retry the command if it fails up to a given number of times (default 0).
 	Retries int `json:"retries,omitempty"`
 	// The working directory to run the command in (default is CWD).
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index acd683d..36c8c8e 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -110,7 +110,7 @@ components:
     onCreate:
       defaults:
         mute: true
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -121,7 +121,7 @@ components:
           windows: powershell
       before:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -152,7 +152,7 @@ components:
             code: 200
       after:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -183,7 +183,7 @@ components:
             code: 200
       onFailure:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -215,7 +215,7 @@ components:
     onDeploy:
       defaults:
         mute: true
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -226,7 +226,7 @@ components:
           windows: powershell
       before:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -257,7 +257,7 @@ components:
             code: 200
       after:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -288,7 +288,7 @@ components:
             code: 200
       onFailure:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -320,7 +320,7 @@ components:
     onRemove:
       defaults:
         mute: true
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -331,7 +331,7 @@ components:
           windows: powershell
       before:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -362,7 +362,7 @@ components:
             code: 200
       after:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:
@@ -393,7 +393,7 @@ components:
             code: 200
       onFailure:
       - mute: false
-        timeout: 1m
+        maxTotalSeconds: 60
         retries: 0
         dir: dir
         env:

From fea78220276fbcf7e7571f0fe356c0176700628a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 29 Apr 2026 11:45:39 -0400
Subject: [PATCH 092/131] change localOS to OS

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 2 +-
 0051-v1beta1-schema/zarf.yaml  | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 507d308..4a41607 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -184,6 +184,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
+- `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`
 
 ### New Fields
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 48200af..e6aa0d0 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -182,7 +182,7 @@ type Component struct {
 // ComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.
 type ComponentTarget struct {
 	// Only deploy component to specified OS.
-	LocalOS string `json:"localOS,omitempty" jsonschema:"enum=linux,enum=darwin,enum=windows"`
+	OS string `json:"os,omitempty" jsonschema:"enum=linux,enum=darwin,enum=windows"`
 	// Only include component for the given package architecture.
 	Architecture string `json:"architecture,omitempty" jsonschema:"enum=amd64,enum=arm64"`
 	// Only include this component when a matching '--flavor' is specified on 'zarf package create'.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 36c8c8e..f7df679 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -42,7 +42,7 @@ components:
   description: Zarf description
   optional: false # Component is required (default behavior)
   target:
-    localOS: darwin
+    os: darwin
     architecture: amd64
     flavor: a-flavor # this will only be used when there are multiple components
   import:

From 73a3e7dcf7a14eff154085343be31244d24cda46 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 30 Apr 2026 11:22:30 -0400
Subject: [PATCH 093/131] add server side apply

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 14 ++++++++++++++
 0051-v1beta1-schema/zarf.yaml  |  2 ++
 2 files changed, 16 insertions(+)

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index e6aa0d0..13b9aa2 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -235,6 +235,13 @@ type Manifest struct {
 	Kustomizations []string `json:"kustomizations,omitempty"`
 	// Whether to not wait for manifest resources to be ready before continuing.
 	NoWait *bool `json:"noWait,omitempty"`
+	// Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy.
+	//   - "true":  always use SSA
+	//   - "false": always use CSA
+	//   - "auto":  use SSA for fresh installs; for upgrades, match whichever strategy
+	//              was used when the chart was first installed
+	// Defaults to "auto" when omitted.
+	ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"`
 	// Template enables go-template processing on these manifests during deploy.
 	Template *bool `json:"template,omitempty"`
 }
@@ -265,6 +272,13 @@ type Chart struct {
 	Values []ChartValue `json:"values,omitempty"`
 	// Whether to validate the chart's values against its JSON schema. Defaults to true.
 	SchemaValidation *bool `json:"schemaValidation,omitempty"`
+	// Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart.
+	//   - "true":  always use SSA
+	//   - "false": always use CSA
+	//   - "auto":  use SSA for fresh installs; for upgrades, match whichever strategy
+	//              was used when the chart was first installed
+	// Defaults to "auto" when omitted.
+	ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"`
 }
 
 // ChartValue maps a values source path to a Helm chart target path.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index f7df679..cced2b9 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -64,6 +64,7 @@ components:
     kustomizations:
     - a-kustomization.yaml
     noWait: true
+    serverSideApply: "auto"
     template: true # Enable go-template processing
   charts:
   - name: chart
@@ -76,6 +77,7 @@ components:
     - sourcePath: ".app.name"
       targetPath: ".appName"
     schemaValidation: true
+    serverSideApply: "auto"
     helmRepository: # Only one of helmRepository, git, oci, or local is allowed
       url: https://stefanprodan.github.io/podinfo
       name: podinfo # replaces repoName since it's only applicable in this situation

From 4625c34d43538c4f59cfc872b912e700ba1f0f6a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 30 Apr 2026 13:54:28 -0400
Subject: [PATCH 094/131] remote component templating

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 4a41607..b85b146 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -625,4 +625,8 @@ information to express the idea and why it was not acceptable.
 
 ### Component Import Schema
 
-Another possibility for the [component config schema](#zarf-component-config-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
\ No newline at end of file
+Another possibility for the [component config schema](#zarf-component-config-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
+
+### Remote Component Templating
+
+Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists. 
\ No newline at end of file

From afae6194b48ce60398fcbcd31fde86409c38d0ef Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 30 Apr 2026 13:57:46 -0400
Subject: [PATCH 095/131] replace onsuccess with onafter

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 2 +-
 0051-v1beta1-schema/package.go | 4 ++--
 0051-v1beta1-schema/zarf.yaml  | 6 +++---
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index b85b146..14bfd2c 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -167,7 +167,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
-- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list.
+- `.components.[x].actions.[onAny].after` will be combined with and replaced by `actions.[onAny].onSuccess`. Any `after` actions will be appended to the `actions.[onAny].onSuccess` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`. Since `.cluster.distro` will be removed, the `.cluster` parent field will be deleted. 
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 13b9aa2..21a8cc0 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -371,8 +371,8 @@ type ComponentActionSet struct {
 	Defaults ComponentActionDefaults `json:"defaults,omitempty"`
 	// Actions to run at the start of an operation.
 	Before []ComponentAction `json:"before,omitempty"`
-	// Actions to run at the end of an operation.
-	After []ComponentAction `json:"after,omitempty"`
+	// Actions to run at the end of an operation if it succeeds.
+	OnSuccess []ComponentAction `json:"onSuccess,omitempty"`
 	// Actions to run if any operation in this set fails.
 	OnFailure []ComponentAction `json:"onFailure,omitempty"`
 }
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index cced2b9..88c3dad 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -152,7 +152,7 @@ components:
             protocol: http
             address: github.com
             code: 200
-      after:
+      onSuccess:
       - mute: false
         maxTotalSeconds: 60
         retries: 0
@@ -257,7 +257,7 @@ components:
             protocol: http
             address: github.com
             code: 200
-      after:
+      onSuccess:
       - mute: false
         maxTotalSeconds: 60
         retries: 0
@@ -362,7 +362,7 @@ components:
             protocol: http
             address: github.com
             code: 200
-      after:
+      onSuccess:
       - mute: false
         maxTotalSeconds: 60
         retries: 0

From 81f6cb25783fdbdef3557b80b46810d8f344f41b Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 30 Apr 2026 16:30:47 -0400
Subject: [PATCH 096/131] variants extend base component

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 49 +++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 14bfd2c..1064efb 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -615,6 +615,10 @@ Why should this ZEP _not_ be implemented?
 ### Component Import Reworks
 Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
+### Component Config 
+
+There is an implicit ordering in a zarf.yaml file, the first component in a list is installed, then the second and so forth. By asking users to break apart their zarf.yaml files into Zarf Component Config files, they may lose this implicit ordering, and it could be more confusing to determine the order of components. 
+
 ## Alternatives
 
 <!--
@@ -623,10 +627,51 @@ not need to be as detailed as the proposal, but should include enough
 information to express the idea and why it was not acceptable.
 -->
 
-### Component Import Schema
+### Component Config Schema
+
+#### List of Components
 
 Another possibility for the [component config schema](#zarf-component-config-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
 
+#### Variants extend base component
+
+Another possibility for the [component config schema](#zarf-component-config-schema) is to have a single `.component` field that can be extended by a list of `.variants`. The `.component` field would be required, and could be imported or published as defined. It could also be extended using the `.variants` field. The logic for extending would exactly mirror the [component import logic](https://docs.zarf.dev/ref/components/#component-imports); the variant would import the base component. 
+
+This would be especially useful when there are multiple configurations of a chart, such as the example below. Each flavor prescribes its own values file and images, but otherwise is the same. A similar situation is seen in the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) of the main Zarf repository. The only change between the two k3s components are the files that vary by architecture.
+
+```yaml
+apiVersion: zarf.dev/v1beta1
+kind: ZarfComponentConfig
+metadata:
+  name: grafana
+component:
+  charts:
+    - name: grafana-config
+      namespace: grafana
+      local:
+        path: chart
+      valuesFiles:
+        - chart/values.yaml
+variants:
+  - target:
+      flavor: upstream
+    charts:
+      - name: grafana
+        valuesFiles:
+          - values/upstream-values.yaml
+    images:
+      - name: docker.io/grafana/grafana:12.4.2
+
+  - target:
+      flavor: enterprise
+    charts:
+      - name: grafana
+        valuesFiles:
+          - values/enterprise-values.yaml
+    images:
+      - name: registry1.dso.mil/ironbank/opensource/grafana/grafana:12.4.2
+```
+
 ### Remote Component Templating
 
-Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists. 
\ No newline at end of file
+Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
\ No newline at end of file

From e83469fdf3777cefeb0381e2ace0112d09be750b Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 1 May 2026 08:12:04 -0400
Subject: [PATCH 097/131] config schema

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 1064efb..c381188 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -633,9 +633,9 @@ information to express the idea and why it was not acceptable.
 
 Another possibility for the [component config schema](#zarf-component-config-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
 
-#### Variants extend base component
+#### Variants Extend Base Component
 
-Another possibility for the [component config schema](#zarf-component-config-schema) is to have a single `.component` field that can be extended by a list of `.variants`. The `.component` field would be required, and could be imported or published as defined. It could also be extended using the `.variants` field. The logic for extending would exactly mirror the [component import logic](https://docs.zarf.dev/ref/components/#component-imports); the variant would import the base component. 
+Another possibility for the [component config schema](#zarf-component-config-schema) is to have a single `.component` field that can be extended by a list of `.variants`. The `.component` field would be required, and could be imported or published as defined. It could also be extended using the `.variants` field. The logic for extending would exactly mirror the [component import logic](https://docs.zarf.dev/ref/components/#component-imports); the variant would import the base component.
 
 This would be especially useful when there are multiple configurations of a chart, such as the example below. Each flavor prescribes its own values file and images, but otherwise is the same. A similar situation is seen in the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) of the main Zarf repository. The only change between the two k3s components are the files that vary by architecture.
 

From 6096d497ec6b9ebc3a0294bdff039cb009e00499 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 1 May 2026 08:13:44 -0400
Subject: [PATCH 098/131] remove ironbank verbiage

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index c381188..2ad980d 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -669,7 +669,7 @@ variants:
         valuesFiles:
           - values/enterprise-values.yaml
     images:
-      - name: registry1.dso.mil/ironbank/opensource/grafana/grafana:12.4.2
+      - name: enterprise.corp.org/grafana/grafana:12.4.2
 ```
 
 ### Remote Component Templating

From 347c83ff0a6f2d4892d2d6952245f269aa8f80fe Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 4 May 2026 10:35:06 -0400
Subject: [PATCH 099/131] mention drawback

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 2ad980d..77ec926 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -613,9 +613,11 @@ Why should this ZEP _not_ be implemented?
 -->
 
 ### Component Import Reworks
-Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. We believe this is a worthwhile tradeoff as this rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
+Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. This rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
-### Component Config 
+Removing the ability to import files directly from packages will add some friction to standalone packages that are imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package to maintain the current structure.  
+
+### Component Config
 
 There is an implicit ordering in a zarf.yaml file, the first component in a list is installed, then the second and so forth. By asking users to break apart their zarf.yaml files into Zarf Component Config files, they may lose this implicit ordering, and it could be more confusing to determine the order of components. 
 

From 23ffc55160d4011a3f1f9f32f88f07a8e92922b3 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 4 May 2026 10:40:39 -0400
Subject: [PATCH 100/131] fix wording

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 77ec926..fd852f9 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -615,7 +615,7 @@ Why should this ZEP _not_ be implemented?
 ### Component Import Reworks
 Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. This rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
-Removing the ability to import files directly from packages will add some friction to standalone packages that are imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package to maintain the current structure.  
+Removing the ability to import from ZarfPackageConfig files will add some friction to standalone packages that are also imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package to maintain the current structure.  
 
 ### Component Config
 

From 4ce466dddbb1e3b7d5dcdbe0300051ce95b05919 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 5 May 2026 10:51:18 -0400
Subject: [PATCH 101/131] correct list

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index fd852f9..73a8860 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -647,7 +647,7 @@ kind: ZarfComponentConfig
 metadata:
   name: grafana
 component:
-  charts:
+  - charts:
     - name: grafana-config
       namespace: grafana
       local:

From 34546a00a641048316f236e3c5d9064de5c5e3d3 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 5 May 2026 15:34:08 -0400
Subject: [PATCH 102/131] remove zarf init config

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 73a8860..9e7e0de 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -201,7 +201,7 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators, [#4528](https://github.com/zarf-dev/zarf/issues/4528), and leave little room for configurability.
 
-A new "services" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.services.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent services don't allow setting specific values, as those services already have Helm charts. There will be validation that ensures Services are only used in packages that are `Kind: ZarfInitConfig`. There will not be a separate schema for `ZarfInitConfig` and `ZarfPackageConfig` objects to avoid complexity.
+A new "services" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.services.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent services don't allow setting specific values, as those services already have Helm charts.
 
 View the full schema in [package.go](package.go#L200-L222). 
 
@@ -215,6 +215,10 @@ View the full schema in [package.go](package.go#L200-L222).
         tolerations: ".injector.tolerations"
 ```
 
+### ZarfInitConfig will be Removed
+
+The `Kind` "ZarfInitConfig" will be removed. Every package will be of kind "ZarfPackageConfig". `zarf init` will default to deploying a package called `zarf-package-init-<cli-version>-<arch>.tar.zst`. A template will be created that exposes the CLI version, so a `zarf.tpl.yaml` file could set the `.metadata.version` field to `[[ .cli.version ]]`. If a package called `zarf-package-init-<arch>-<cli-version>.tar.zst` is not found in the cache or current directory, Zarf will prompt the user to pull the default zarf-dev init package. `zarf init` will continue to accept custom packages, for example, `zarf init <zarf-package-my-custom-init>`. If the package has no Zarf services, then Zarf will error and ask the user to run `zarf package deploy` instead. 
+
 ### ZarfComponentConfig
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only by v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.

From aa3cb32c6383c1b4cd0097d0dfda60a6a37a0012 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 09:54:13 -0400
Subject: [PATCH 103/131] reasoning for drawback

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 9e7e0de..1645586 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -619,7 +619,7 @@ Why should this ZEP _not_ be implemented?
 ### Component Import Reworks
 Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. This rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
-Removing the ability to import from ZarfPackageConfig files will add some friction to standalone packages that are also imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package to maintain the current structure.  
+Removing the ability to import from ZarfPackageConfig files will add some friction to standalone packages that are also imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package that imports the component config to maintain the current structure. This drawback is deemed necessary to avoid packages that are only meant for import and not deployable as a standalone package. This has cause confusion among many users, and forcing creators to explicitly make a sub-package as deployable will avoid this issue.
 
 ### Component Config
 

From 1e744bffd16cca5168368940cde4f0777a19b2f1 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 10:24:12 -0400
Subject: [PATCH 104/131] avoid variants in component config

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 1645586..b894d6c 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -678,6 +678,10 @@ variants:
       - name: enterprise.corp.org/grafana/grafana:12.4.2
 ```
 
+#### Avoid Variants in ZarfComponentConfig
+
+The component config structure could be simplified by not introducing variants. If a user has multiple versions of a component differentiated by the `target` field then they will have to create a ZarfComponentConfig file for each target. This will result in more files, however, it will keep the mental model simple. Every ZarfComponentConfig would contain exactly one component, and the import tree would be easy to follow. 
+
 ### Remote Component Templating
 
 Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
\ No newline at end of file

From 99b0b104ff44dcf7838e91acd8b38fb4eabb381a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 11:12:00 -0400
Subject: [PATCH 105/131] change Zarf services to an enum

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md          | 21 ++++++++-------
 0051-v1beta1-schema/componentConfig.go |  4 +--
 0051-v1beta1-schema/package.go         | 36 ++++++++------------------
 0051-v1beta1-schema/zarf.yaml          |  8 +-----
 4 files changed, 25 insertions(+), 44 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index b894d6c..780c418 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -189,7 +189,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 ### New Fields
 
-- `.components[x].services` will be introduced to avoid magic names in Init package components. See [Zarf Services](#zarf-services) for more details.
+- `.components[x].service` will be introduced to avoid magic names in Init package components. See [Zarf Services](#zarf-services) for more details.
 
 ### Behavior Changes
 
@@ -201,23 +201,24 @@ There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`
 
 In the v1alpha1 schema, Zarf looks at init component names to determine when to run certain logic. For instance, the injector is always run when an init component has the name "zarf-seed-registry". These magical names have caused confusion for custom init package creators, [#4528](https://github.com/zarf-dev/zarf/issues/4528), and leave little room for configurability.
 
-A new "services" key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. It'll also allow for setting specific properties using Zarf values. For instance, a user will be able to set tolerations for the injector dynamically on deploy by setting `.services.injector.values.tolerations` to `".injector.tolerations"`. The registry and agent services don't allow setting specific values, as those services already have Helm charts.
+A new `service` key under components will make the inherent coupling between the init package and the Zarf CLI more transparent. The field is an enum with the allowed values `registry`, `seed-registry`, `injector`, `agent`, and `git-server`.
 
-View the full schema in [package.go](package.go#L200-L222). 
+View the full schema in [package.go](package.go#L200).
 
 ```yaml
 - name: zarf-seed-registry
-  services:
-    isRegistry: true
-    injector:
-      enabled: true
-      values:
-        tolerations: ".injector.tolerations"
+  service: seed-registry
+- name: zarf-injector
+  service: injector
+- name: zarf-registry
+  service: registry
+- name: zarf-agent
+  service: agent
 ```
 
 ### ZarfInitConfig will be Removed
 
-The `Kind` "ZarfInitConfig" will be removed. Every package will be of kind "ZarfPackageConfig". `zarf init` will default to deploying a package called `zarf-package-init-<cli-version>-<arch>.tar.zst`. A template will be created that exposes the CLI version, so a `zarf.tpl.yaml` file could set the `.metadata.version` field to `[[ .cli.version ]]`. If a package called `zarf-package-init-<arch>-<cli-version>.tar.zst` is not found in the cache or current directory, Zarf will prompt the user to pull the default zarf-dev init package. `zarf init` will continue to accept custom packages, for example, `zarf init <zarf-package-my-custom-init>`. If the package has no Zarf services, then Zarf will error and ask the user to run `zarf package deploy` instead. 
+The `Kind` "ZarfInitConfig" will be removed. Every package will be of kind "ZarfPackageConfig". `zarf init` will default to deploying a package called `zarf-package-init-<cli-version>-<arch>.tar.zst`. A template will be created that exposes the CLI version, so a `zarf.tpl.yaml` file could set the `.metadata.version` field to `[[ .cli.version ]]`. If a package called `zarf-package-init-<arch>-<cli-version>.tar.zst` is not found in the cache or current directory, Zarf will prompt the user to pull the default zarf-dev init package. `zarf init` will continue to accept custom packages, for example, `zarf init <zarf-package-my-custom-init>`. If no component in the package declares a `.service`, Zarf will error and ask the user to run `zarf package deploy` instead. 
 
 ### ZarfComponentConfig
 
diff --git a/0051-v1beta1-schema/componentConfig.go b/0051-v1beta1-schema/componentConfig.go
index 067d844..353cd1f 100644
--- a/0051-v1beta1-schema/componentConfig.go
+++ b/0051-v1beta1-schema/componentConfig.go
@@ -44,8 +44,8 @@ type ImportableComponent struct {
 	Repositories []string `json:"repositories,omitempty"`
 	// Custom commands to run at various stages of a package lifecycle.
 	Actions ComponentActions `json:"actions,omitempty"`
-	// Zarf CLI services and infrastructure such as the registry, injector, and agent.
-	Services ComponentServices `json:"services,omitempty"`
+	// The Zarf CLI service this component provides, such as the registry, injector, or agent.
+	Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"`
 }
 
 // Variant is a component definition with a required filter for when it applies.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 21a8cc0..755e0ce 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -161,8 +161,8 @@ type Component struct {
 	Target ComponentTarget `json:"target,omitempty"`
 	// Import a component from another Zarf component config.
 	Import ComponentImport `json:"import,omitempty"`
-	// Zarf CLI services and infrastructure such as the registry, injector, and agent.
-	Services ComponentServices `json:"services,omitempty"`
+	// The Zarf CLI service this component provides, such as the registry, injector, or agent.
+	Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"`
 	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
 	Manifests []Manifest `json:"manifests,omitempty"`
 	// Helm charts to install during package deploy.
@@ -197,29 +197,15 @@ type ComponentImport struct {
 	URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"`
 }
 
-// ComponentServices defines Zarf CLI services to enable for an init component.
-type ComponentServices struct {
-	// Whether this component provides a registry.
-	IsRegistry bool `json:"isRegistry,omitempty"`
-	// Injector configuration for the component.
-	Injector *Injector `json:"injector,omitempty"`
-	// Whether this component provides an agent.
-	IsAgent bool `json:"isAgent,omitempty"`
-}
-
-// Injector defines the configuration for the Zarf injector.
-type Injector struct {
-	// Whether the injector is enabled.
-	Enabled bool `json:"enabled"`
-	// Values for the injector.
-	Values *InjectorValues `json:"values,omitempty"`
-}
-
-// InjectorValues defines configurable values for the Zarf injector.
-type InjectorValues struct {
-	// Tolerations for the injector pod.
-	Tolerations string `json:"tolerations,omitempty"`
-}
+// Service identifies which Zarf CLI service a component provides.
+type Service string
+const (
+	ServiceRegistry Service = "registry"
+	ServiceSeedRegistry Service = "seed-registry"
+	ServiceInjector Service = "injector"
+	ServiceAgent Service = "agent"
+	ServiceGitServer Service = "git-server"
+)
 
 // Manifest defines raw manifests Zarf will deploy as a helm chart.
 type Manifest struct {
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 88c3dad..f464d9f 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -48,13 +48,7 @@ components:
   import:
     path: ABCD # Only path or URL will be used, not both
     url: oci://
-  services:
-    isRegistry: false
-    injector:
-      enabled: true
-      values:
-        tolerations: ".injector.tolerations"
-    isAgent: false
+  service: registry # one of: registry, seed-registry, injector, agent, git-server
   manifests:
   - name: manifest
     namespace: manifest-ns

From 6264652ec392af2fe0c9bdc40010eeccf9adde8c Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 11:16:32 -0400
Subject: [PATCH 106/131] brevity

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 780c418..2a3fbbf 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -206,14 +206,11 @@ A new `service` key under components will make the inherent coupling between the
 View the full schema in [package.go](package.go#L200).
 
 ```yaml
-- name: zarf-seed-registry
-  service: seed-registry
-- name: zarf-injector
-  service: injector
 - name: zarf-registry
   service: registry
 - name: zarf-agent
   service: agent
+  ...
 ```
 
 ### ZarfInitConfig will be Removed

From 9738cdd4c8ca6a74b05fd9ec70e3b01e06769ff3 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 12:04:40 -0400
Subject: [PATCH 107/131] change component config proposal

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md          | 19 +++++++++++--------
 0051-v1beta1-schema/componentConfig.go | 16 ++++------------
 2 files changed, 15 insertions(+), 20 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 2a3fbbf..2378fc1 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -167,7 +167,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
-- `.components.[x].actions.[onAny].after` will be combined with and replaced by `actions.[onAny].onSuccess`. Any `after` actions will be appended to the `actions.[onAny].onSuccess` list.
+- `.components.[x].actions.[onAny].after` will be combined with and replaced by `actions.[onAny].onSuccess`. Any `after` actions will be prepended to the `actions.[onAny].onSuccess` list.
 - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`. Since `.cluster.distro` will be removed, the `.cluster` parent field will be deleted. 
@@ -221,7 +221,7 @@ The `Kind` "ZarfInitConfig" will be removed. Every package will be of kind "Zarf
 
 The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig called ZarfComponentConfig. ZarfComponentConfig files will allow declaring a component to be imported from other packages. It will have its own schema, and this schema will be verified on create and publish. ZarfComponentConfigs will be importable only by v1beta1 packages. Components from other ZarfPackageConfigs will not be importable in v1beta1 packages.
 
-A ZarfComponentConfig must declare either the `component` or `variants` field. The `component` field is a single object representing a component that is importable by any package. The `variants` field is a list of components where each entry must specify the `.target` to differentiate itself from the other components (e.g. flavors, OSes, or architectures). Zarf will error if two components under `variants` have the same value for `.target`. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
+Each ZarfComponentConfig declares exactly one component under the `component` field. If a user wants multiple variations of a component differentiated by flavor, OS, or architecture, they create one ZarfComponentConfig file per variation and set the `.component.target` field on each. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
@@ -233,7 +233,7 @@ The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint,
 
 Skeleton packages will be replaced by remote components. Instead of publishing an entire package, users will be able to publish a ZarfComponentConfig. This component will behave similarly to Skeleton packages in that local resources will be published alongside it, while remote resources will be pulled at create time.
 
-Remote components will be published using the new command `zarf component publish <component-file> <oci-repo>`. This command will have the flags `--flavor` and `--all-variants`. When `--all-variants` is used, all variants will be published regardless of their `.target` block. If the `.component` block is supplied instead of a `.variants` block, `--all-variants` will have no effect.
+Remote components will be published using the new command `zarf component publish <component-file> <oci-repo>`. This command will have the flag `--flavor` to publish a component whose `.component.target.flavor` matches the supplied value.
 
 Unlike Skeleton packages, which are published with unresolved templates, remote components must be fully templated before publishing. By templating before publish, we avoid issues with validating a non-templated package ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and stay aligned with the overall [Package Templates](#package-templates) strategy.
 
@@ -607,6 +607,7 @@ Major milestones might include:
 
 - 2025-10-21: Proposal submitted
 - 2026-02-12: Introduced Zarf Component Config, package templating changes, and Zarf services
+- 2026-05-06: Simplified ZarfComponentConfig to one component per file; moved variants to alternatives
 
 ## Drawbacks
 
@@ -633,9 +634,15 @@ information to express the idea and why it was not acceptable.
 
 ### Component Config Schema
 
+#### Variants in ZarfComponentConfig
+
+A previous version of this proposal allowed a ZarfComponentConfig to declare either a `.component` field or a `.variants[]` field. The `.component` field was a single object representing a component importable by any package. The `.variants` field was a list of components where each entry had to specify a `.target` block (e.g. flavors, OSes, or architectures) to differentiate itself from the other entries. Zarf would error if two entries under `.variants` shared the same target. The `zarf component publish` command would have grown a `--all-variants` flag to publish every variant in one file at once.
+
+This was rejected in favor of "exactly one component per file" to keep the mental model simple. With variants, a single file could expand into many components depending on flavor/OS/arch, and authors had to reason about which entry applied where. Forcing a 1:1 file-to-component mapping makes the import tree easy to follow at the cost of a few extra files for components with multiple targets.
+
 #### List of Components
 
-Another possibility for the [component config schema](#zarf-component-config-schema) instead of allowing for one of `.component` or `.variants[]` was to simply have a list of components. The list of components would allow for multiple entries, so long as each entry had a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The list key `.components[]` would likely confuse users on this aspect. Separate keys for `.component` and `.variants[]` also allow for built-in schema validation, requiring the `.target` key with `.variants[]` but not with `.component`.
+Another possibility for the [component config schema](#zarf-component-config-schema) was to have a list of components under a `.components[]` field, where each entry must specify a `.target` block. This was rejected since a major change in this system is that `ZarfComponentConfig` files represent a single component. The plural `.components[]` key would likely confuse users on this aspect.
 
 #### Variants Extend Base Component
 
@@ -676,10 +683,6 @@ variants:
       - name: enterprise.corp.org/grafana/grafana:12.4.2
 ```
 
-#### Avoid Variants in ZarfComponentConfig
-
-The component config structure could be simplified by not introducing variants. If a user has multiple versions of a component differentiated by the `target` field then they will have to create a ZarfComponentConfig file for each target. This will result in more files, however, it will keep the mental model simple. Every ZarfComponentConfig would contain exactly one component, and the import tree would be easy to follow. 
-
 ### Remote Component Templating
 
 Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
\ No newline at end of file
diff --git a/0051-v1beta1-schema/componentConfig.go b/0051-v1beta1-schema/componentConfig.go
index 353cd1f..c455a8f 100644
--- a/0051-v1beta1-schema/componentConfig.go
+++ b/0051-v1beta1-schema/componentConfig.go
@@ -11,11 +11,8 @@ type ComponentConfig struct {
 	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
 	// Component metadata.
 	Metadata ComponentMetadata `json:"metadata"`
-	// A single component definition that applies in all contexts. Exactly one of Component or Variants must be set.
-	Component *ImportableComponent `json:"component,omitempty" jsonschema:"oneof_required=component"`
-	// A list of component variants, each with a distinct .target filter. Use this when the
-	// component has different definitions for different flavors, OSes, or architectures.
-	Variants []Variant `json:"variants,omitempty" jsonschema:"oneof_required=variants"`
+	// The single component this config defines.
+	Component Component `json:"component"`
 	// Constant template values applied on deploy.
 	Constants []Constant `json:"constants,omitempty"`
 	// Variable template values applied on deploy.
@@ -30,6 +27,8 @@ type ComponentConfig struct {
 type ImportableComponent struct {
 	// Import a component from another Zarf component config.
 	Import ComponentImport `json:"import,omitempty"`
+	// Filter when this component is included in package creation or deployment.
+	Target ComponentTarget `json:"target,omitempty"`
 	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
 	Manifests []Manifest `json:"manifests,omitempty"`
 	// Helm charts to install during package deploy.
@@ -48,13 +47,6 @@ type ImportableComponent struct {
 	Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"`
 }
 
-// Variant is a component definition with a required filter for when it applies.
-type Variant struct {
-	ImportableComponent
-	// Filter when this variant is included in package creation or deployment.
-	Target ComponentTarget `json:"target"`
-}
-
 // ComponentMetadata holds metadata about a component config.
 type ComponentMetadata struct {
 	// Name to identify this component config.

From cf16df50b1f38ae7365207d369a9710b63484937 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 14:23:50 -0400
Subject: [PATCH 108/131] component level action defaults

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 2378fc1..9b05b91 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -685,4 +685,10 @@ variants:
 
 ### Remote Component Templating
 
-Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
\ No newline at end of file
+Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
+
+### Component Level Action Defaults
+
+Action defaults could be set once at the component level rather than separately under each action set (`onCreate`, `onDeploy`, `onRemove`). This would shrink the wide surface area of the schema. 
+
+This was rejected. Create and deploy often run on separate hosts and have different jobs: `onCreate` actions typically pull files or load images as docker tars, while `onDeploy` actions typically run `kubectl` or stand up a cluster. Sharing defaults between them across that boundary creates an awkward mental model. The [example v1beta1 zarf.yaml](./zarf.yaml) is large because every action set has its own defaults block, but in practice actions are an escape hatch used sparingly. It is rare for a real component to define both `onCreate` and `onDeploy` actions.
\ No newline at end of file

From 50d9a874c5833a066ce21ae3f02a4c0197de86c9 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 14:31:34 -0400
Subject: [PATCH 109/131] fix grammar

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 9b05b91..974eeb3 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -174,7 +174,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendor` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
-- `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append, to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
+- `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
 
 #### Renamed Fields
 
@@ -185,7 +185,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
-- `.components.[x].repos` will be renamed to `.components.[x].repositories`
+- `.components.[x].repos` will be renamed to `.components.[x].repositories`.
 
 ### New Fields
 
@@ -215,7 +215,7 @@ View the full schema in [package.go](package.go#L200).
 
 ### ZarfInitConfig will be Removed
 
-The `Kind` "ZarfInitConfig" will be removed. Every package will be of kind "ZarfPackageConfig". `zarf init` will default to deploying a package called `zarf-package-init-<cli-version>-<arch>.tar.zst`. A template will be created that exposes the CLI version, so a `zarf.tpl.yaml` file could set the `.metadata.version` field to `[[ .cli.version ]]`. If a package called `zarf-package-init-<arch>-<cli-version>.tar.zst` is not found in the cache or current directory, Zarf will prompt the user to pull the default zarf-dev init package. `zarf init` will continue to accept custom packages, for example, `zarf init <zarf-package-my-custom-init>`. If no component in the package declares a `.service`, Zarf will error and ask the user to run `zarf package deploy` instead. 
+The `Kind` "ZarfInitConfig" will be removed. Every package will be of kind "ZarfPackageConfig". `zarf init` will default to deploying a package called `zarf-package-init-<arch>-<cli-version>.tar.zst`. A template will be created that exposes the CLI version, so a `zarf.tpl.yaml` file could set the `.metadata.version` field to `[[ .cli.version ]]`. If a package called `zarf-package-init-<arch>-<cli-version>.tar.zst` is not found in the cache or current directory, Zarf will prompt the user to pull the default zarf-dev init package. `zarf init` will continue to accept custom packages, for example, `zarf init <zarf-package-my-custom-init>`. If no component in the package declares a `.service`, Zarf will error and ask the user to run `zarf package deploy` instead. 
 
 ### ZarfComponentConfig
 
@@ -302,7 +302,7 @@ components:
           - values.yaml
 ```
 
-I want to upgrade to the v1beta1 schema, so I run `zarf dev upgrade-schema . > zarf.yaml`. Which produces:
+I want to upgrade to the v1beta1 schema, so I run `zarf dev upgrade-schema . > zarf.yaml`, which produces:
 
 ```yaml
 apiVersion: zarf.dev/v1beta1
@@ -487,7 +487,7 @@ How will security be reviewed, and by whom?
 How will UX be reviewed, and by whom?
 -->
 
-The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. The docs website added a page for migration to inform users how to switch https://docs.zarf.dev/best-practices/data-injections-migration/.
+The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. The docs website added a [migration page](https://docs.zarf.dev/best-practices/data-injections-migration/) to inform users how to switch.
 
 The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to its replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables.
 
@@ -506,7 +506,7 @@ The `Chart` object will be restructured as seen in [package.go](package.go#L242-
 
 During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.git.URL`. This is consistent with the current Zarf behavior.
 
-Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub object, or drop it when not applicable.
+Zarf uses the top-level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048-schema-update-process](../0048-schema-update-process/README.md#converting-removed-fields). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note that this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev upgrade-schema` will simply move the top-level `version` field to the right sub-object, or drop it when not applicable.
 
 ### Zarf Component Config Schema
 
@@ -618,11 +618,11 @@ Why should this ZEP _not_ be implemented?
 ### Component Import Reworks
 Removing the ability to import components from packages directly, and instead requiring Zarf Component Config files, will require a sizable portion of the user base to rewrite files. This rewrite should leave users with a clearer directory structure, enhanced package validation, and a more intuitive import system.
 
-Removing the ability to import from ZarfPackageConfig files will add some friction to standalone packages that are also imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package that imports the component config to maintain the current structure. This drawback is deemed necessary to avoid packages that are only meant for import and not deployable as a standalone package. This has cause confusion among many users, and forcing creators to explicitly make a sub-package as deployable will avoid this issue.
+Removing the ability to import from ZarfPackageConfig files will add some friction to standalone packages that are also imported. For instance, the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) in the init package is deployable as a standalone package and imported by the init package. The proposed system would require creating a component config as well as a separate standalone k3s package that imports the component config to maintain the current structure. This drawback is deemed necessary to avoid packages that are only meant for import and not deployable as a standalone package. This has caused confusion among many users, and forcing creators to explicitly make a sub-package deployable will avoid this issue.
 
 ### Component Config
 
-There is an implicit ordering in a zarf.yaml file, the first component in a list is installed, then the second and so forth. By asking users to break apart their zarf.yaml files into Zarf Component Config files, they may lose this implicit ordering, and it could be more confusing to determine the order of components. 
+There is an implicit ordering in a zarf.yaml file: the first component in a list is installed, then the second, and so forth. By asking users to break apart their zarf.yaml files into Zarf Component Config files, they may lose this implicit ordering, and it could be more confusing to determine the order of components. 
 
 ## Alternatives
 
@@ -648,7 +648,7 @@ Another possibility for the [component config schema](#zarf-component-config-sch
 
 Another possibility for the [component config schema](#zarf-component-config-schema) is to have a single `.component` field that can be extended by a list of `.variants`. The `.component` field would be required, and could be imported or published as defined. It could also be extended using the `.variants` field. The logic for extending would exactly mirror the [component import logic](https://docs.zarf.dev/ref/components/#component-imports); the variant would import the base component.
 
-This would be especially useful when there are multiple configurations of a chart, such as the example below. Each flavor prescribes its own values file and images, but otherwise is the same. A similar situation is seen in the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) of the main Zarf repository. The only change between the two k3s components are the files that vary by architecture.
+This would be especially useful when there are multiple configurations of a chart, such as the example below. Each flavor prescribes its own values file and images, but otherwise is the same. A similar situation is seen in the [k3s sub-package](https://github.com/zarf-dev/zarf/blob/main/packages/distros/k3s/zarf.yaml) of the main Zarf repository. The only differences between the two k3s components are the files that vary by architecture.
 
 ```yaml
 apiVersion: zarf.dev/v1beta1
@@ -685,10 +685,10 @@ variants:
 
 ### Remote Component Templating
 
-Remote components cannot be templated during import, this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
+Remote components cannot be templated during import; this is a removed feature from its predecessor Skeleton packages. This allows Zarf to validate the component before it's published ([#4491](https://github.com/zarf-dev/zarf/issues/4491)) and is necessary since package templating now occurs before create. A potential alternative is a templated remote component where `zarf dev template oci://ghcr.io/<my-remote-component>` would download the component from OCI and template it. The user would then be able to import the component from their local directory. This was rejected because it adds complexity for a niche use case. This could be a future enhancement if the demand exists.
 
 ### Component Level Action Defaults
 
-Action defaults could be set once at the component level rather than separately under each action set (`onCreate`, `onDeploy`, `onRemove`). This would shrink the wide surface area of the schema. 
+Action defaults could be set once at the component level rather than separately under each action set (`onCreate`, `onDeploy`, `onRemove`). This would reduce the schema's surface area. 
 
 This was rejected. Create and deploy often run on separate hosts and have different jobs: `onCreate` actions typically pull files or load images as docker tars, while `onDeploy` actions typically run `kubectl` or stand up a cluster. Sharing defaults between them across that boundary creates an awkward mental model. The [example v1beta1 zarf.yaml](./zarf.yaml) is large because every action set has its own defaults block, but in practice actions are an escape hatch used sparingly. It is rare for a real component to define both `onCreate` and `onDeploy` actions.
\ No newline at end of file

From 804113acd501ab88191a9878d13da70868d63dda Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 6 May 2026 16:16:35 -0400
Subject: [PATCH 110/131] path & url to paths

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 13 ++++++++-----
 0051-v1beta1-schema/package.go |  8 ++++----
 0051-v1beta1-schema/zarf.yaml  |  5 +++--
 3 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 974eeb3..4c9612f 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -160,7 +160,6 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].dataInjections` will be removed. https://docs.zarf.dev/best-practices/data-injections-migration/ details migrating off of this field.
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
 - `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
-- `.components.[x].import.name` will be removed given that component imports will be changed. See [ZarfComponentConfig](#zarfcomponentconfig).
 - `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are no plans to use it currently.
 
 #### Replaced / Restructured Fields
@@ -175,6 +174,8 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
 - `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
+- `.components.[x].import.name` will be removed given that components will only be importable from component config files so there is not a name to select. See [ZarfComponentConfig](#zarfcomponentconfig).
+- `.components.[x].import.path` and `.components.[x].import.url` will be consolidated into a single `.components.[x].import.paths` list. Any entry starting with `oci://` is treated as a remote component; all other entries are treated as local file paths. See [ZarfComponentConfig](#zarfcomponentconfig).
 
 #### Renamed Fields
 
@@ -225,7 +226,7 @@ Each ZarfComponentConfig declares exactly one component under the `component` fi
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
-The `.import.path` field will not accept directories; users will give the file path to the ZarfComponentConfig file they are importing.
+The `.import.paths` field is a list of references to ZarfComponentConfig files. Each entry is either a local file path or an `oci://` URL; `oci://` entries are pulled at create time as remote components. Directories are not accepted. When more than one entry is given, every referenced component must share the same name, and at most one of them must be compatible with the active package target (flavor, OS, architecture) at create time otherwise Zarf will error.
 
 The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint, inspect, and find-images) will accept component config files. For example, `zarf dev inspect definition my-component-config.yaml`.
 
@@ -243,7 +244,7 @@ The Zarf v1alpha1 schema allows for package templates during create using the ##
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.
 
-`zarf dev template` will have logic to follow local component imports. If the `.import.path` points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and edit the value of `import.path` to be `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path to `<base>.gen.yaml`. Zarf will template imports after the current file is finished templating, so a user will be able to template the value of `.import.path` into a `<base>.tpl.yaml` file and Zarf will template the given file.
+`zarf dev template` will have logic to follow local component imports. For any entry in `.import.paths` that points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and rewrite the entry to `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path entries to `<base>.gen.yaml` directly. Zarf will template imports after the current file is finished templating, so a user will be able to template a value into an entry of `.import.paths` and Zarf will template the resulting file.
 
 Package templates will be required to have a value; otherwise the command will fail.
 
@@ -407,10 +408,12 @@ metadata:
 components:
   - name: logging
     import:
-      path: logging.yaml
+      paths:
+        - logging.yaml
   - name: monitoring
     import:
-      url: oci://ghcr.io/my-org/components/monitoring:1.0.0
+      paths:
+        - oci://ghcr.io/my-org/components/monitoring:1.0.0
 ```
 
 I can then create my package as usual:
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 755e0ce..05a26bd 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -191,10 +191,10 @@ type ComponentTarget struct {
 
 // ComponentImport is a reference to an imported Zarf component config.
 type ComponentImport struct {
-	// The path to the component config file to import.
-	Path string `json:"path,omitempty"`
-	// The URL to a Zarf component config to import via OCI.
-	URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"`
+	// Paths to component config files to import. Each entry is either a local file path
+	// or an oci:// URL When multiple paths are given, every referenced component must share the same name
+	// and at most one of them must be compatible with the package target.
+	Paths []string `json:"paths,omitempty"`
 }
 
 // Service identifies which Zarf CLI service a component provides.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index f464d9f..52386d4 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -46,8 +46,9 @@ components:
     architecture: amd64
     flavor: a-flavor # this will only be used when there are multiple components
   import:
-    path: ABCD # Only path or URL will be used, not both
-    url: oci://
+    paths: # Local file paths or oci:// URLs. Multiple entries must reference components with the same name and at most one compatible at create time.
+      - ./components/a-component.yaml
+      - oci://ghcr.io/my-org/components/a-component:1.0.0
   service: registry # one of: registry, seed-registry, injector, agent, git-server
   manifests:
   - name: manifest

From d557b222448f1cbbbede03b3fd1929ef85ec700e Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 7 May 2026 12:12:15 -0400
Subject: [PATCH 111/131] remove variables and constants

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md          |  3 +-
 0051-v1beta1-schema/componentConfig.go |  4 --
 0051-v1beta1-schema/package.go         | 55 --------------------
 0051-v1beta1-schema/zarf.yaml          | 69 --------------------------
 4 files changed, 2 insertions(+), 129 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 4c9612f..ccfb5ed 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -159,6 +159,8 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].group` will be removed. A similar functionality was introduced with the field `components[x].target.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
 - `.components.[x].dataInjections` will be removed. https://docs.zarf.dev/best-practices/data-injections-migration/ details migrating off of this field.
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
+- `.variables` and `.constants` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead. While values will always be mutable on deploy, creators will be able to choose which values in their chart are mutable using `sourcePath/targetPath`. Similarly, creators decide which fields in manifests are mutable through values. 
+- `.components.[x].actions.[onAny].setVariable` and `.components.[x].actions.[onAny].setVariables` will be removed. The existing `.components.[x].actions.[onAny].setValues` field is the replacement.
 - `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
 - `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are no plans to use it currently.
 
@@ -167,7 +169,6 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
 - `.components.[x].actions.[onAny].after` will be combined with and replaced by `actions.[onAny].onSuccess`. Any `after` actions will be prepended to the `actions.[onAny].onSuccess` list.
-- `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`.
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`. Since `.cluster.distro` will be removed, the `.cluster` parent field will be deleted. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendor` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
diff --git a/0051-v1beta1-schema/componentConfig.go b/0051-v1beta1-schema/componentConfig.go
index c455a8f..d574ce5 100644
--- a/0051-v1beta1-schema/componentConfig.go
+++ b/0051-v1beta1-schema/componentConfig.go
@@ -13,10 +13,6 @@ type ComponentConfig struct {
 	Metadata ComponentMetadata `json:"metadata"`
 	// The single component this config defines.
 	Component Component `json:"component"`
-	// Constant template values applied on deploy.
-	Constants []Constant `json:"constants,omitempty"`
-	// Variable template values applied on deploy.
-	Variables []InteractiveVariable `json:"variables,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values Values `json:"values,omitempty"`
 	// Zarf-generated publish data for the component config.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 05a26bd..9e0125d 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -4,16 +4,6 @@
 // Package v1beta1 holds the definition of the v1beta1 Zarf Package.
 package v1beta1
 
-// VariableType represents a type of a Zarf package variable.
-type VariableType string
-
-const (
-	// RawVariableType is the default type for a Zarf package variable.
-	RawVariableType VariableType = "raw"
-	// FileVariableType loads the variable contents from a file.
-	FileVariableType VariableType = "file"
-)
-
 // PackageKind is an enum of the different kinds of Zarf packages.
 type PackageKind string
 
@@ -38,10 +28,6 @@ type Package struct {
 	Build BuildData `json:"build,omitempty"`
 	// List of components to deploy in this package.
 	Components []Component `json:"components" jsonschema:"minItems=1"`
-	// Constant template values applied on deploy.
-	Constants []Constant `json:"constants,omitempty"`
-	// Variable template values applied on deploy.
-	Variables []InteractiveVariable `json:"variables,omitempty"`
 	// Values imports Zarf values files for templating and overriding Helm values.
 	Values Values `json:"values,omitempty"`
 	// Documentation files included in the package.
@@ -108,45 +94,6 @@ type Values struct {
 	Schema string `json:"schema,omitempty"`
 }
 
-// Variable represents a variable that has a value set programmatically.
-type Variable struct {
-	// The name to be used for the variable.
-	Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"`
-	// Whether to mark this variable as sensitive to not print it in the log.
-	Sensitive bool `json:"sensitive,omitempty"`
-	// Whether to automatically indent the variable's value (if multiline) when templating.
-	AutoIndent bool `json:"autoIndent,omitempty"`
-	// An optional regex pattern that a variable value must match before a package deployment can continue.
-	Pattern string `json:"pattern,omitempty"`
-	// Changes the handling of a variable to load contents differently.
-	Type VariableType `json:"type,omitempty" jsonschema:"enum=raw,enum=file"`
-}
-
-// InteractiveVariable is a variable that can be used to prompt a user for more information.
-type InteractiveVariable struct {
-	Variable `json:",inline"`
-	// A description of the variable to be used when prompting the user a value.
-	Description string `json:"description,omitempty"`
-	// The default value to use for the variable.
-	Default string `json:"default,omitempty"`
-	// Whether to prompt the user for input for this variable.
-	Prompt bool `json:"prompt,omitempty"`
-}
-
-// Constant is a value used to dynamically template resources or run in actions.
-type Constant struct {
-	// The name to be used for the constant.
-	Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"`
-	// The value to set for the constant during deploy.
-	Value string `json:"value"`
-	// A description of the constant.
-	Description string `json:"description,omitempty"`
-	// Whether to automatically indent the constant's value (if multiline) when templating.
-	AutoIndent bool `json:"autoIndent,omitempty"`
-	// An optional regex pattern that a constant value must match before a package can be created.
-	Pattern string `json:"pattern,omitempty"`
-}
-
 // Component is the primary functional grouping of assets to deploy by Zarf.
 type Component struct {
 	// The name of the component.
@@ -395,8 +342,6 @@ type ComponentAction struct {
 	Cmd string `json:"cmd,omitempty"`
 	// Indicates a preference for a shell for the provided cmd.
 	Shell *Shell `json:"shell,omitempty"`
-	// An array of variables to update with the output of the command.
-	SetVariables []Variable `json:"setVariables,omitempty"`
 	// An array of values to set with the output of the command.
 	SetValues []SetValue `json:"setValues,omitempty"`
 	// Description of the action to be displayed during package execution instead of the command.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 52386d4..e63dd2d 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -128,12 +128,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -159,12 +153,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -190,12 +178,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -233,12 +215,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -264,12 +240,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -295,12 +265,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -338,12 +302,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -369,12 +327,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -400,12 +352,6 @@ components:
           darwin: sh
           linux: sh
           windows: powershell
-        setVariables:
-        - name: VAR
-          sensitive: false
-          autoIndent: true
-          pattern: ".+"
-          type: raw
         setValues:
           - key: .json
         description: action-description
@@ -419,18 +365,3 @@ components:
             protocol: http
             address: github.com
             code: 200
-constants:
-- name: CONSTANT
-  value: constant-value
-  description: constant-value
-  autoIndent: false
-  pattern: ".+"
-variables:
-- name: VAR
-  sensitive: false
-  autoIndent: true
-  pattern: ".+"
-  type: raw
-  description: var
-  default: whatever
-  prompt: false

From d6cddfc25ab71ed7a11509f065786a80fdd9a009 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Fri, 8 May 2026 10:47:53 -0400
Subject: [PATCH 112/131] defaults

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index ccfb5ed..8d4cd8d 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -695,4 +695,4 @@ Remote components cannot be templated during import; this is a removed feature f
 
 Action defaults could be set once at the component level rather than separately under each action set (`onCreate`, `onDeploy`, `onRemove`). This would reduce the schema's surface area. 
 
-This was rejected. Create and deploy often run on separate hosts and have different jobs: `onCreate` actions typically pull files or load images as docker tars, while `onDeploy` actions typically run `kubectl` or stand up a cluster. Sharing defaults between them across that boundary creates an awkward mental model. The [example v1beta1 zarf.yaml](./zarf.yaml) is large because every action set has its own defaults block, but in practice actions are an escape hatch used sparingly. It is rare for a real component to define both `onCreate` and `onDeploy` actions.
\ No newline at end of file
+This was rejected. Create and deploy often run on separate hosts and have different jobs: `onCreate` actions typically pull files or load images as docker tars, while `onDeploy` actions typically run `kubectl` or stand up a cluster. Sharing defaults across that boundary creates an awkward mental model. The [example v1beta1 zarf.yaml](./zarf.yaml) is large because every action set has its own defaults block, but in practice actions are an escape hatch used sparingly. It is rare for a real component to define both `onCreate` and `onDeploy` actions.
\ No newline at end of file

From e0199feea5d9e16e9a48c075d1632a6225c7bb18 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Mon, 11 May 2026 16:50:22 -0400
Subject: [PATCH 113/131] import object list rather than paths

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 14 +++++++-------
 0051-v1beta1-schema/package.go | 20 ++++++++++++++++----
 0051-v1beta1-schema/zarf.yaml  |  7 ++++---
 3 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 8d4cd8d..32c148e 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -176,7 +176,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
 - `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
 - `.components.[x].import.name` will be removed given that components will only be importable from component config files so there is not a name to select. See [ZarfComponentConfig](#zarfcomponentconfig).
-- `.components.[x].import.path` and `.components.[x].import.url` will be consolidated into a single `.components.[x].import.paths` list. Any entry starting with `oci://` is treated as a remote component; all other entries are treated as local file paths. See [ZarfComponentConfig](#zarfcomponentconfig).
+- `.components.[x].import.path` and `.components.[x].import.url` will be changed into `.components.[x].import.local.[x].path` and `.components.[x].import.remote.[x].url`. All entries from both are combined when applying component compatibility rules. See [ZarfComponentConfig](#zarfcomponentconfig). These fields are a list of objects instead of a list of strings to enable future sibling fields. For instance, we may introduce a field `.components.[x].import.remote.[x].verify` to enable verifying the signature of signed remote components.
 
 #### Renamed Fields
 
@@ -227,7 +227,7 @@ Each ZarfComponentConfig declares exactly one component under the `component` fi
 
 The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
-The `.import.paths` field is a list of references to ZarfComponentConfig files. Each entry is either a local file path or an `oci://` URL; `oci://` entries are pulled at create time as remote components. Directories are not accepted. When more than one entry is given, every referenced component must share the same name, and at most one of them must be compatible with the active package target (flavor, OS, architecture) at create time otherwise Zarf will error.
+`.import.local` is a list of local file path references to ZarfComponentConfig files; directories are not accepted. `.import.remote` is a list of `oci://` URL references to remote component configs pulled at create time. All entries from both fields are combined when applying compatibility rules: when more than one entry is given, every referenced component must share the same name, and at most one of them must be compatible with the active package target (flavor, OS, architecture) at create time otherwise Zarf will error.
 
 The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint, inspect, and find-images) will accept component config files. For example, `zarf dev inspect definition my-component-config.yaml`.
 
@@ -245,7 +245,7 @@ The Zarf v1alpha1 schema allows for package templates during create using the ##
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.
 
-`zarf dev template` will have logic to follow local component imports. For any entry in `.import.paths` that points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and rewrite the entry to `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path entries to `<base>.gen.yaml` directly. Zarf will template imports after the current file is finished templating, so a user will be able to template a value into an entry of `.import.paths` and Zarf will template the resulting file.
+`zarf dev template` will have logic to follow local component imports. For any entry in `.import.local` whose `path` points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and rewrite the entry to `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path entries to `<base>.gen.yaml` directly. Zarf will template imports after the current file is finished templating, so a user will be able to template a value into an entry of `.import.local` and Zarf will template the resulting file.
 
 Package templates will be required to have a value; otherwise the command will fail.
 
@@ -409,12 +409,12 @@ metadata:
 components:
   - name: logging
     import:
-      paths:
-        - logging.yaml
+      local:
+        - path: logging.yaml
   - name: monitoring
     import:
-      paths:
-        - oci://ghcr.io/my-org/components/monitoring:1.0.0
+      remote:
+        - url: oci://ghcr.io/my-org/components/monitoring:1.0.0
 ```
 
 I can then create my package as usual:
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 9e0125d..3b657b9 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -138,10 +138,22 @@ type ComponentTarget struct {
 
 // ComponentImport is a reference to an imported Zarf component config.
 type ComponentImport struct {
-	// Paths to component config files to import. Each entry is either a local file path
-	// or an oci:// URL When multiple paths are given, every referenced component must share the same name
-	// and at most one of them must be compatible with the package target.
-	Paths []string `json:"paths,omitempty"`
+	// Local file path references to component config files to import.
+	Local []ComponentImportLocal `json:"local,omitempty"`
+	// OCI URL references to remote component config files to import; pulled at create time.
+	Remote []ComponentImportRemote `json:"remote,omitempty"`
+}
+
+// ComponentImportLocal is a local file path reference to a component config.
+type ComponentImportLocal struct {
+	// The local file path to the component config.
+	Path string `json:"path"`
+}
+
+// ComponentImportRemote is a remote OCI URL reference to a component config.
+type ComponentImportRemote struct {
+	// The OCI URL of the remote component config.
+	URL string `json:"url"`
 }
 
 // Service identifies which Zarf CLI service a component provides.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index e63dd2d..f914ea2 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -46,9 +46,10 @@ components:
     architecture: amd64
     flavor: a-flavor # this will only be used when there are multiple components
   import:
-    paths: # Local file paths or oci:// URLs. Multiple entries must reference components with the same name and at most one compatible at create time.
-      - ./components/a-component.yaml
-      - oci://ghcr.io/my-org/components/a-component:1.0.0
+    local:
+      - path: ./components/a-component.yaml
+    remote:
+      - url: oci://ghcr.io/my-org/components/a-component:1.0.0
   service: registry # one of: registry, seed-registry, injector, agent, git-server
   manifests:
   - name: manifest

From 442f3904ecfa6718c69947a960f7976bd8147f96 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 09:16:56 -0400
Subject: [PATCH 114/131] kind

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 3b657b9..b91e4b1 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -8,8 +8,6 @@ package v1beta1
 type PackageKind string
 
 const (
-	// ZarfInitConfig is the kind of Zarf package used during `zarf init`.
-	ZarfInitConfig PackageKind = "ZarfInitConfig"
 	// ZarfPackageConfig is the default kind of Zarf package.
 	ZarfPackageConfig PackageKind = "ZarfPackageConfig"
 	// APIVersion is the api version of this package.
@@ -21,7 +19,7 @@ type Package struct {
 	// The API version of the Zarf package.
 	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
 	// The kind of Zarf package.
-	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"`
+	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfPackageConfig"`
 	// Package metadata.
 	Metadata Metadata `json:"metadata,omitempty"`
 	// Zarf-generated package build data.

From 92b738cc449ab3beb3cc9dced089f2ae3e0b2c54 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 09:18:21 -0400
Subject: [PATCH 115/131] terminal->hostname

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 2 +-
 0051-v1beta1-schema/zarf.yaml  | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 32c148e..cf286de 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -183,6 +183,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 `zarf dev upgrade-schema` will automatically migrate these fields.
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
+- `.build.terminal` will be renamed to `.build.hostname`.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index b91e4b1..8160a72 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -53,7 +53,7 @@ type Metadata struct {
 // BuildData is written during package create to track details of the created package.
 type BuildData struct {
 	// The machine name that created this package.
-	Terminal string `json:"terminal,omitempty"`
+	Hostname string `json:"hostname,omitempty"`
 	// The username who created this package.
 	User string `json:"user,omitempty"`
 	// The architecture this package was created on.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index f914ea2..3e550ac 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -16,7 +16,7 @@ metadata:
     anyway-you-want-it: thats-the-way-you-need-it
   allowNamespaceOverride: true
 build: # Everything here is created by Zarf not by users
-  terminal: my-computer
+  hostname: my-computer
   user: my-user
   architecture: amd64
   timestamp: 2021-09-01T00:00:00Z

From fac9f3d4c8929e53308f606dace45ac839ca2f6a Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 09:19:43 -0400
Subject: [PATCH 116/131] no wait to skip wait

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 4 ++--
 0051-v1beta1-schema/zarf.yaml  | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index cf286de..7ee2983 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -184,6 +184,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`.
 - `.build.terminal` will be renamed to `.build.hostname`.
+- `.components.[x].manifests.[x].noWait` and `.components.[x].charts.[x].noWait` will be renamed to `skipWait`.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 8160a72..33157fe 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -177,7 +177,7 @@ type Manifest struct {
 	// List of local kustomization paths or remote URLs to include in the package.
 	Kustomizations []string `json:"kustomizations,omitempty"`
 	// Whether to not wait for manifest resources to be ready before continuing.
-	NoWait *bool `json:"noWait,omitempty"`
+	SkipWait *bool `json:"skipWait,omitempty"`
 	// Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy.
 	//   - "true":  always use SSA
 	//   - "false": always use CSA
@@ -208,7 +208,7 @@ type Chart struct {
 	// The name of the Helm release to create (defaults to the Zarf name of the chart).
 	ReleaseName string `json:"releaseName,omitempty"`
 	// Whether to not wait for chart resources to be ready before continuing.
-	NoWait *bool `json:"noWait,omitempty"`
+	SkipWait *bool `json:"skipWait,omitempty"`
 	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
 	// List of value sources mapped to their Helm override targets.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 3e550ac..05cb523 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -59,14 +59,14 @@ components:
     kustomizeAllowAnyDirectory: false
     kustomizations:
     - a-kustomization.yaml
-    noWait: true
+    skipWait: true
     serverSideApply: "auto"
     template: true # Enable go-template processing
   charts:
   - name: chart
     namespace: chart-ns
     releaseName: chart-release
-    noWait: false
+    skipWait: false
     valuesFiles:
     - values.yaml
     values:

From 91151ee4f91c27e5a9f43a98e94db04646538a8e Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 09:21:38 -0400
Subject: [PATCH 117/131] make server side apply an enum

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 33157fe..b1a0e9e 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -164,6 +164,14 @@ const (
 	ServiceGitServer Service = "git-server"
 )
 
+// ServerSideApplyMode controls when server-side apply is used during deploy.
+type ServerSideApplyMode string
+const (
+	ServerSideApplyEnabled  ServerSideApplyMode = "true"
+	ServerSideApplyDisabled ServerSideApplyMode = "false"
+	ServerSideApplyAuto     ServerSideApplyMode = "auto"
+)
+
 // Manifest defines raw manifests Zarf will deploy as a helm chart.
 type Manifest struct {
 	// A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.
@@ -184,7 +192,7 @@ type Manifest struct {
 	//   - "auto":  use SSA for fresh installs; for upgrades, match whichever strategy
 	//              was used when the chart was first installed
 	// Defaults to "auto" when omitted.
-	ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"`
+	ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty"`
 	// Template enables go-template processing on these manifests during deploy.
 	Template *bool `json:"template,omitempty"`
 }
@@ -221,7 +229,7 @@ type Chart struct {
 	//   - "auto":  use SSA for fresh installs; for upgrades, match whichever strategy
 	//              was used when the chart was first installed
 	// Defaults to "auto" when omitted.
-	ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"`
+	ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty"`
 }
 
 // ChartValue maps a values source path to a Helm chart target path.

From 277f092bd373bf00a72048e6b1fcb2e97d14146d Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 09:24:47 -0400
Subject: [PATCH 118/131] target to destination

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 2 +-
 0051-v1beta1-schema/zarf.yaml  | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 7ee2983..bd118e7 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -190,6 +190,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`.
+- `.components.[x].files.[x].target` will be renamed to `.components.[x].files.[x].destination`.
 
 ### New Fields
 
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index b1a0e9e..f4d46d9 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -279,7 +279,7 @@ type File struct {
 	// Optional SHA256 checksum of the file.
 	Shasum string `json:"shasum,omitempty"`
 	// The absolute or relative path where the file or folder should be copied to during package deploy.
-	Target string `json:"target"`
+	Destination string `json:"destination"`
 	// Determines if the file should be made executable during package deploy.
 	Executable bool `json:"executable,omitempty"`
 	// List of symlinks to create during package deploy.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 05cb523..d075cb6 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -88,7 +88,7 @@ components:
       path: chart
   files:
   - source: source-file.txt
-    target: target-file.txt
+    destination: target-file.txt
     shasum: shasum
     executable: false
     symlinks:

From 096c5912124fa5ba05111eb4c88e24350eb005a2 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 10:07:34 -0400
Subject: [PATCH 119/131] use int32 across the board

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index f4d46d9..aa5a3d6 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -333,9 +333,9 @@ type ComponentActionDefaults struct {
 	// Hide the output of commands during execution (default false).
 	Mute bool `json:"mute,omitempty"`
 	// Default timeout in seconds for commands (default to 0, no timeout).
-	MaxTotalSeconds int `json:"maxTotalSeconds,omitempty"`
+	MaxTotalSeconds int32 `json:"maxTotalSeconds,omitempty"`
 	// Retry commands a given number of times if they fail (default 0).
-	Retries int `json:"retries,omitempty"`
+	Retries int32 `json:"retries,omitempty"`
 	// Working directory for commands (default CWD).
 	Dir string `json:"dir,omitempty"`
 	// Additional environment variables for commands.
@@ -349,9 +349,9 @@ type ComponentAction struct {
 	// Hide the output of the command during package deployment (default false).
 	Mute *bool `json:"mute,omitempty"`
 	// Timeout in seconds for the command (default to 0, no timeout for cmd actions and 300, 5 minutes for wait actions).
-	MaxTotalSeconds *int `json:"maxTotalSeconds,omitempty"`
+	MaxTotalSeconds *int32 `json:"maxTotalSeconds,omitempty"`
 	// Retry the command if it fails up to a given number of times (default 0).
-	Retries int `json:"retries,omitempty"`
+	Retries int32 `json:"retries,omitempty"`
 	// The working directory to run the command in (default is CWD).
 	Dir *string `json:"dir,omitempty"`
 	// Additional environment variables to set for the command.
@@ -419,7 +419,7 @@ type ComponentActionWaitNetwork struct {
 	// The address to wait for.
 	Address string `json:"address" jsonschema:"example=localhost:8080,example=1.1.1.1"`
 	// The HTTP status code to wait for if using http or https.
-	Code int `json:"code,omitempty" jsonschema:"example=200,example=404"`
+	Code int32 `json:"code,omitempty" jsonschema:"example=200,example=404"`
 }
 
 // Shell represents the desired shell to use for a given command.

From b8ac552d2a12914dd4e84e5b442088f60026a338 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Wed, 13 May 2026 10:09:38 -0400
Subject: [PATCH 120/131] update

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 4 ++--
 0051-v1beta1-schema/zarf.yaml  | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index bd118e7..5645064 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -191,6 +191,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`.
 - `.components.[x].files.[x].target` will be renamed to `.components.[x].files.[x].destination`.
+- `.components.[x].files.[x].shasum` will be renamed to `.components.[x].files.[x].checksum`. The field accepts the format `<algorithm>:<checksum>` (e.g. `sha256:abc123`); if no algorithm prefix is provided, sha256 is assumed.
 
 ### New Fields
 
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index aa5a3d6..4f4d374 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -276,8 +276,8 @@ type OCISource struct {
 type File struct {
 	// Local folder or file path or remote URL to pull into the package.
 	Source string `json:"source"`
-	// Optional SHA256 checksum of the file.
-	Shasum string `json:"shasum,omitempty"`
+	// Optional checksum of the file in the format <algorithm>:<checksum> (e.g. sha256:abc123). Defaults to sha256 if no algorithm is specified.
+	Checksum string `json:"checksum,omitempty"`
 	// The absolute or relative path where the file or folder should be copied to during package deploy.
 	Destination string `json:"destination"`
 	// Determines if the file should be made executable during package deploy.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index d075cb6..28261ae 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -89,7 +89,7 @@ components:
   files:
   - source: source-file.txt
     destination: target-file.txt
-    shasum: shasum
+    checksum: sha256:abc123
     executable: false
     symlinks:
     - /path/to/symlink

From d0fb44320a0a956940903666c3561fae80d8e6cd Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Thu, 14 May 2026 15:12:51 -0400
Subject: [PATCH 121/131] remove default

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 5645064..9427019 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -157,6 +157,7 @@ The v1beta1 schema will remove, replace, and rename several fields. View this [z
 If a package has these fields defined then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
 
 - `.components.[x].group` will be removed. A similar functionality was introduced with the field `components[x].target.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
+- `.components.[x].default` will be removed. It was used to determine the default `.components[x].group`. It also gave the default to the (Y/N) prompt during interactive deploys, this use was secondary and not important enough to keep the field around. 
 - `.components.[x].dataInjections` will be removed. https://docs.zarf.dev/best-practices/data-injections-migration/ details migrating off of this field.
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
 - `.variables` and `.constants` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead. While values will always be mutable on deploy, creators will be able to choose which values in their chart are mutable using `sourcePath/targetPath`. Similarly, creators decide which fields in manifests are mutable through values. 
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 4f4d374..97c6f3e 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -98,8 +98,6 @@ type Component struct {
 	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
 	// Message to include during package deploy describing the purpose of this component.
 	Description string `json:"description,omitempty"`
-	// Determines the default Y/N state for installing this component on package deploy.
-	Default bool `json:"default,omitempty"`
 	// Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.
 	Optional *bool `json:"optional,omitempty"`
 	// Filter when this component is included in package creation or deployment.

From 86db53fc58561f57d48233258742c10f04af5385 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 10:50:28 -0500
Subject: [PATCH 122/131] metadata to package metadata

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 97c6f3e..dce4a97 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -21,7 +21,7 @@ type Package struct {
 	// The kind of Zarf package.
 	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfPackageConfig"`
 	// Package metadata.
-	Metadata Metadata `json:"metadata,omitempty"`
+	Metadata PackageMetadata `json:"metadata,omitempty"`
 	// Zarf-generated package build data.
 	Build BuildData `json:"build,omitempty"`
 	// List of components to deploy in this package.
@@ -33,7 +33,7 @@ type Package struct {
 }
 
 // Metadata holds information about the package.
-type Metadata struct {
+type PackageMetadata struct {
 	// Name to identify this Zarf package.
 	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
 	// Additional information about this Zarf package.

From f9ac46ce62b3b3caeedf636a4d01f4f7a891e16f Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 10:57:00 -0500
Subject: [PATCH 123/131] create kustomize sub-field

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  |  1 +
 0051-v1beta1-schema/package.go | 16 ++++++++++++----
 0051-v1beta1-schema/zarf.yaml  |  8 +++++---
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 9427019..40d5b96 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -178,6 +178,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
 - `.components.[x].import.name` will be removed given that components will only be importable from component config files so there is not a name to select. See [ZarfComponentConfig](#zarfcomponentconfig).
 - `.components.[x].import.path` and `.components.[x].import.url` will be changed into `.components.[x].import.local.[x].path` and `.components.[x].import.remote.[x].url`. All entries from both are combined when applying component compatibility rules. See [ZarfComponentConfig](#zarfcomponentconfig). These fields are a list of objects instead of a list of strings to enable future sibling fields. For instance, we may introduce a field `.components.[x].import.remote.[x].verify` to enable verifying the signature of signed remote components.
+- `.components.[x].manifests.[x].kustomizations`, `.components.[x].manifests.[x].kustomizeAllowAnyDirectory`, and `.components.[x].manifests.[x].enableKustomizePlugins` will be moved into a `.components.[x].manifests.[x].kustomize` sub-object. The fields become `kustomize.files`, `kustomize.allowAnyDirectory`, and `kustomize.enablePlugins` respectively.
 
 #### Renamed Fields
 
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index dce4a97..765b65d 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -170,6 +170,16 @@ const (
 	ServerSideApplyAuto     ServerSideApplyMode = "auto"
 )
 
+// KustomizeManifest defines kustomization settings for a manifest.
+type KustomizeManifest struct {
+	// List of local kustomization paths or remote URLs to include in the package.
+	Files []string `json:"files,omitempty"`
+	// Allow traversing directory above the current directory if needed for kustomization.
+	AllowAnyDirectory bool `json:"allowAnyDirectory,omitempty"`
+	// Enable kustomize plugins when building manifests.
+	EnablePlugins bool `json:"enablePlugins,omitempty"`
+}
+
 // Manifest defines raw manifests Zarf will deploy as a helm chart.
 type Manifest struct {
 	// A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.
@@ -178,10 +188,8 @@ type Manifest struct {
 	Namespace string `json:"namespace,omitempty"`
 	// List of local K8s YAML files or remote URLs to deploy (in order).
 	Files []string `json:"files,omitempty"`
-	// Allow traversing directory above the current directory if needed for kustomization.
-	KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty"`
-	// List of local kustomization paths or remote URLs to include in the package.
-	Kustomizations []string `json:"kustomizations,omitempty"`
+	// Kustomize settings for this manifest.
+	Kustomize *KustomizeManifest `json:"kustomize,omitempty"`
 	// Whether to not wait for manifest resources to be ready before continuing.
 	SkipWait *bool `json:"skipWait,omitempty"`
 	// Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 28261ae..28691f1 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -56,9 +56,11 @@ components:
     namespace: manifest-ns
     files:
     - a-file.yaml
-    kustomizeAllowAnyDirectory: false
-    kustomizations:
-    - a-kustomization.yaml
+    kustomize:
+      files:
+      - a-kustomization.yaml
+      allowAnyDirectory: false
+      enablePlugins: true
     skipWait: true
     serverSideApply: "auto"
     template: true # Enable go-template processing

From e2129b62093e6ff1d0e3cae2349b490737c533ae Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 10:59:39 -0500
Subject: [PATCH 124/131] actions.mute to actions.silent

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 1 +
 0051-v1beta1-schema/package.go | 4 ++--
 0051-v1beta1-schema/zarf.yaml  | 6 +++---
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 40d5b96..85d2c78 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -189,6 +189,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].manifests.[x].noWait` and `.components.[x].charts.[x].noWait` will be renamed to `skipWait`.
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
+- `.components.[x].actions.[default/onAny].mute` will be renamed to `.components.[x].actions.[default/onAny].silent`.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 765b65d..2734d46 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -337,7 +337,7 @@ type ComponentActionSet struct {
 // ComponentActionDefaults sets the default configs for child actions.
 type ComponentActionDefaults struct {
 	// Hide the output of commands during execution (default false).
-	Mute bool `json:"mute,omitempty"`
+	Silent bool `json:"silent,omitempty"`
 	// Default timeout in seconds for commands (default to 0, no timeout).
 	MaxTotalSeconds int32 `json:"maxTotalSeconds,omitempty"`
 	// Retry commands a given number of times if they fail (default 0).
@@ -353,7 +353,7 @@ type ComponentActionDefaults struct {
 // ComponentAction represents a single action to run during a Zarf package operation.
 type ComponentAction struct {
 	// Hide the output of the command during package deployment (default false).
-	Mute *bool `json:"mute,omitempty"`
+	Silent *bool `json:"silent,omitempty"`
 	// Timeout in seconds for the command (default to 0, no timeout for cmd actions and 300, 5 minutes for wait actions).
 	MaxTotalSeconds *int32 `json:"maxTotalSeconds,omitempty"`
 	// Retry the command if it fails up to a given number of times (default 0).
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 28691f1..94532bf 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -109,7 +109,7 @@ components:
   actions:
     onCreate:
       defaults:
-        mute: true
+        silent: true
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -196,7 +196,7 @@ components:
             code: 200
     onDeploy:
       defaults:
-        mute: true
+        silent: true
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -283,7 +283,7 @@ components:
             code: 200
     onRemove:
       defaults:
-        mute: true
+        silent: true
         maxTotalSeconds: 60
         retries: 0
         dir: dir

From 6e1db1c368ac33090ea2ad0fb5a4a004d529beb4 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 11:02:44 -0500
Subject: [PATCH 125/131] enable values

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  |  1 +
 0051-v1beta1-schema/package.go | 12 ++++++------
 0051-v1beta1-schema/zarf.yaml  | 13 +++++++++++--
 3 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 85d2c78..84770db 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -190,6 +190,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required.
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].mute` will be renamed to `.components.[x].actions.[default/onAny].silent`.
+- `.components.[x].manifests.[x].template`, `.components.[x].files.[x].template`, and `.components.[x].actions.[onAny].template` will be renamed to `enableValues`.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 2734d46..339c13a 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -199,8 +199,8 @@ type Manifest struct {
 	//              was used when the chart was first installed
 	// Defaults to "auto" when omitted.
 	ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty"`
-	// Template enables go-template processing on these manifests during deploy.
-	Template *bool `json:"template,omitempty"`
+	// EnableValues enables go-template processing on these manifests during deploy.
+	EnableValues *bool `json:"enableValues,omitempty"`
 }
 
 // Chart defines a helm chart to be deployed.
@@ -292,8 +292,8 @@ type File struct {
 	Symlinks []string `json:"symlinks,omitempty"`
 	// Local folder or file to be extracted from a 'source' archive.
 	ExtractPath string `json:"extractPath,omitempty"`
-	// Template enables go-template processing on this file during deploy.
-	Template *bool `json:"template,omitempty"`
+	// EnableValues enables go-template processing on this file during deploy.
+	EnableValues *bool `json:"enableValues,omitempty"`
 }
 
 // Image defines an OCI image to include in the package.
@@ -372,8 +372,8 @@ type ComponentAction struct {
 	Description string `json:"description,omitempty"`
 	// Wait for a condition to be met before continuing.
 	Wait *ComponentActionWait `json:"wait,omitempty"`
-	// Template enables go-template processing on the cmd field.
-	Template *bool `json:"template,omitempty"`
+	// EnableValues enables go-template processing on the cmd field.
+	EnableValues *bool `json:"enableValues,omitempty"`
 }
 
 // SetValueType declares the expected input back from the cmd, allowing structured data to be parsed.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 94532bf..2801cf0 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -63,7 +63,7 @@ components:
       enablePlugins: true
     skipWait: true
     serverSideApply: "auto"
-    template: true # Enable go-template processing
+    enableValues: true # Enable go-template processing
   charts:
   - name: chart
     namespace: chart-ns
@@ -96,7 +96,7 @@ components:
     symlinks:
     - /path/to/symlink
     extractPath: /path/to/extract
-    template: false # Disable go-template processing for this file
+    enableValues: false # Disable go-template processing for this file
   images:
     - name: podinfo:v1
       source: "registry" # optional - registry is the default value
@@ -127,6 +127,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -152,6 +153,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -177,6 +179,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -214,6 +217,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -239,6 +243,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -264,6 +269,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -301,6 +307,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -326,6 +333,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh
@@ -351,6 +359,7 @@ components:
         env:
         - ENV_VAR=FOO
         cmd: echo hello
+        enableValues: true
         shell:
           darwin: sh
           linux: sh

From acdb961e32f1ce94c178a16e33d4c745aacc7b74 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 11:08:01 -0500
Subject: [PATCH 126/131] skip schema validation

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  |  1 +
 0051-v1beta1-schema/package.go | 10 +++++-----
 0051-v1beta1-schema/zarf.yaml  |  2 +-
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 84770db..05e490b 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -191,6 +191,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].mute` will be renamed to `.components.[x].actions.[default/onAny].silent`.
 - `.components.[x].manifests.[x].template`, `.components.[x].files.[x].template`, and `.components.[x].actions.[onAny].template` will be renamed to `enableValues`.
+- `.components.[x].charts.[x].schemaValidation` will be renamed to `skipSchemaValidation`. The field now defaults to `false`, so schema validation continue to run by default.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 339c13a..64e468a 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -191,7 +191,7 @@ type Manifest struct {
 	// Kustomize settings for this manifest.
 	Kustomize *KustomizeManifest `json:"kustomize,omitempty"`
 	// Whether to not wait for manifest resources to be ready before continuing.
-	SkipWait *bool `json:"skipWait,omitempty"`
+	SkipWait bool `json:"skipWait,omitempty"`
 	// Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy.
 	//   - "true":  always use SSA
 	//   - "false": always use CSA
@@ -222,13 +222,13 @@ type Chart struct {
 	// The name of the Helm release to create (defaults to the Zarf name of the chart).
 	ReleaseName string `json:"releaseName,omitempty"`
 	// Whether to not wait for chart resources to be ready before continuing.
-	SkipWait *bool `json:"skipWait,omitempty"`
+	SkipWait bool `json:"skipWait,omitempty"`
 	// List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.
 	ValuesFiles []string `json:"valuesFiles,omitempty"`
 	// List of value sources mapped to their Helm override targets.
 	Values []ChartValue `json:"values,omitempty"`
-	// Whether to validate the chart's values against its JSON schema. Defaults to true.
-	SchemaValidation *bool `json:"schemaValidation,omitempty"`
+	// Skip validation of the chart's values against its JSON schema. Defaults to false.
+	SkipSchemaValidation bool `json:"skipSchemaValidation,omitempty"`
 	// Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart.
 	//   - "true":  always use SSA
 	//   - "false": always use CSA
@@ -373,7 +373,7 @@ type ComponentAction struct {
 	// Wait for a condition to be met before continuing.
 	Wait *ComponentActionWait `json:"wait,omitempty"`
 	// EnableValues enables go-template processing on the cmd field.
-	EnableValues *bool `json:"enableValues,omitempty"`
+	EnableValues bool `json:"enableValues,omitempty"`
 }
 
 // SetValueType declares the expected input back from the cmd, allowing structured data to be parsed.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 2801cf0..4948eff 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -74,7 +74,7 @@ components:
     values:
     - sourcePath: ".app.name"
       targetPath: ".appName"
-    schemaValidation: true
+    skipSchemaValidation: false
     serverSideApply: "auto"
     helmRepository: # Only one of helmRepository, git, oci, or local is allowed
       url: https://stefanprodan.github.io/podinfo

From a1c12a15c310029018291fc99a8e33206c3f9cb7 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 11:15:51 -0500
Subject: [PATCH 127/131] prevent namespace override

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md  | 3 ++-
 0051-v1beta1-schema/package.go | 4 ++--
 0051-v1beta1-schema/zarf.yaml  | 2 +-
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 05e490b..9c08e2b 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -191,7 +191,8 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].mute` will be renamed to `.components.[x].actions.[default/onAny].silent`.
 - `.components.[x].manifests.[x].template`, `.components.[x].files.[x].template`, and `.components.[x].actions.[onAny].template` will be renamed to `enableValues`.
-- `.components.[x].charts.[x].schemaValidation` will be renamed to `skipSchemaValidation`. The field now defaults to `false`, so schema validation continue to run by default.
+- `.components.[x].charts.[x].schemaValidation` will be renamed to `skipSchemaValidation`. The field now defaults to `false` instead of `true`, so schema validation continue to run by default.
+- `.metadata.allowNamespaceOverride` will be renamed to `preventNamespaceOverride`. The field now defaults to `false` instead of `true`, so namespace overrides continue to be allowed by default.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
 - `.components.[x].repos` will be renamed to `.components.[x].repositories`.
diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 64e468a..349bbec 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -46,8 +46,8 @@ type PackageMetadata struct {
 	Architecture string `json:"architecture,omitempty" jsonschema:"example=arm64,example=amd64"`
 	// Annotations are key-value pairs that can be used to store metadata about the package.
 	Annotations map[string]string `json:"annotations,omitempty"`
-	// Whether to allow namespace overrides for this package.
-	AllowNamespaceOverride *bool `json:"allowNamespaceOverride,omitempty"`
+	// Prevent namespace overrides for this package.
+	PreventNamespaceOverride bool `json:"preventNamespaceOverride,omitempty"`
 }
 
 // BuildData is written during package create to track details of the created package.
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 4948eff..4422671 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -14,7 +14,7 @@ metadata:
     vendor: my-vendor
     image: https://my-image-url-to-use-in-deprecated-zarf-ui
     anyway-you-want-it: thats-the-way-you-need-it
-  allowNamespaceOverride: true
+  preventNamespaceOverride: false
 build: # Everything here is created by Zarf not by users
   hostname: my-computer
   user: my-user

From 8bb04fa4a2d6a135a51967f876b0fff4da288731 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 11:18:45 -0500
Subject: [PATCH 128/131] boolean fields

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/package.go | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/0051-v1beta1-schema/package.go b/0051-v1beta1-schema/package.go
index 349bbec..4cb6b85 100644
--- a/0051-v1beta1-schema/package.go
+++ b/0051-v1beta1-schema/package.go
@@ -99,7 +99,7 @@ type Component struct {
 	// Message to include during package deploy describing the purpose of this component.
 	Description string `json:"description,omitempty"`
 	// Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.
-	Optional *bool `json:"optional,omitempty"`
+	Optional bool `json:"optional,omitempty"`
 	// Filter when this component is included in package creation or deployment.
 	Target ComponentTarget `json:"target,omitempty"`
 	// Import a component from another Zarf component config.
@@ -200,7 +200,7 @@ type Manifest struct {
 	// Defaults to "auto" when omitted.
 	ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty"`
 	// EnableValues enables go-template processing on these manifests during deploy.
-	EnableValues *bool `json:"enableValues,omitempty"`
+	EnableValues bool `json:"enableValues,omitempty"`
 }
 
 // Chart defines a helm chart to be deployed.
@@ -293,7 +293,7 @@ type File struct {
 	// Local folder or file to be extracted from a 'source' archive.
 	ExtractPath string `json:"extractPath,omitempty"`
 	// EnableValues enables go-template processing on this file during deploy.
-	EnableValues *bool `json:"enableValues,omitempty"`
+	EnableValues bool `json:"enableValues,omitempty"`
 }
 
 // Image defines an OCI image to include in the package.

From 2e02965a7fc232b8503fa9752ea17a038d46dce5 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 13:16:35 -0500
Subject: [PATCH 129/131] specifying wait behavior

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 9c08e2b..cd79564 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -201,13 +201,13 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 ### New Fields
 
-- `.components[x].service` will be introduced to avoid magic names in Init package components. See [Zarf Services](#zarf-services) for more details.
+- `.components.[x].service` will be introduced to avoid magic names in Init package components. See [Zarf Services](#zarf-services) for more details.
 
 ### Behavior Changes
 
 #### Wait Changes
 
-There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf waits until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks.
+There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf waits until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks. When migrating from v1alpha1 to v1beta1 if `cluster.condition` is not set, then it will be automatically populated with "exists" for backwards compatibility with existing packages.
 
 #### Zarf Services
 

From 9f19f1f51c81622fa1236c8d881d0e7ec225301e Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 13:25:32 -0500
Subject: [PATCH 130/131] fix english

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index cd79564..0f91200 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -154,16 +154,16 @@ The v1beta1 schema will remove, replace, and rename several fields. View this [z
 
 #### Removed Fields
 
-If a package has these fields defined then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
+If a package has these fields defined, then `zarf dev upgrade-schema` will error and print a recommendation for an alternative.
 
-- `.components.[x].group` will be removed. A similar functionality was introduced with the field `components[x].target.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
+- `.components.[x].group` will be removed. Similar functionality was introduced with the field `components[x].target.flavor`. This shifts component selection to the create side, and is the recommended replacement. 
 - `.components.[x].default` will be removed. It was used to determine the default `.components[x].group`. It also gave the default to the (Y/N) prompt during interactive deploys, this use was secondary and not important enough to keep the field around. 
 - `.components.[x].dataInjections` will be removed. https://docs.zarf.dev/best-practices/data-injections-migration/ details migrating off of this field.
 - `.components.[x].charts.[x].variables` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead.
 - `.variables` and `.constants` will be removed. Users are encouraged to use [Zarf values](../0021-zarf-values/) instead. While values will always be mutable on deploy, creators will be able to choose which values in their chart are mutable using `sourcePath/targetPath`. Similarly, creators decide which fields in manifests are mutable through values. 
 - `.components.[x].actions.[onAny].setVariable` and `.components.[x].actions.[onAny].setVariables` will be removed. The existing `.components.[x].actions.[onAny].setValues` field is the replacement.
 - `.metadata.yolo` will be removed. Its successor is connected deployments [#4580](https://github.com/zarf-dev/zarf/issues/4580).
-- `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are no plans to use it currently.
+- `.components.[x].only.cluster.distro` will be removed. This field was never used for anything and there are currently no plans to use it.
 
 #### Replaced / Restructured Fields
 
@@ -191,7 +191,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 - `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`.
 - `.components.[x].actions.[default/onAny].mute` will be renamed to `.components.[x].actions.[default/onAny].silent`.
 - `.components.[x].manifests.[x].template`, `.components.[x].files.[x].template`, and `.components.[x].actions.[onAny].template` will be renamed to `enableValues`.
-- `.components.[x].charts.[x].schemaValidation` will be renamed to `skipSchemaValidation`. The field now defaults to `false` instead of `true`, so schema validation continue to run by default.
+- `.components.[x].charts.[x].schemaValidation` will be renamed to `skipSchemaValidation`. The field now defaults to `false` instead of `true`, so schema validation continues to run by default.
 - `.metadata.allowNamespaceOverride` will be renamed to `preventNamespaceOverride`. The field now defaults to `false` instead of `true`, so namespace overrides continue to be allowed by default.
 - `.components.[x].only` will be renamed to `.components.[x].target`.
 - `.components.[x].only.localOS` will be renamed to `.components.[x].target.os`.
@@ -207,7 +207,7 @@ If a package has these fields defined then `zarf dev upgrade-schema` will error
 
 #### Wait Changes
 
-There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf waits until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks. When migrating from v1alpha1 to v1beta1 if `cluster.condition` is not set, then it will be automatically populated with "exists" for backwards compatibility with existing packages.
+There will be a behavior change in `.components[x].actions.[onAny].wait.cluster`. In the v1alpha1 ZarfPackageConfig, when `.cluster.condition` is empty, Zarf waits until the resource exists. In the v1beta1 schema, when `.cluster.condition` is empty, Zarf will wait for the resource to be ready using kstatus readiness checks. When migrating from v1alpha1 to v1beta1, if `cluster.condition` is not set, then it will be automatically populated with "exists" for backwards compatibility with existing packages.
 
 #### Zarf Services
 
@@ -235,9 +235,9 @@ The v1beta1 APIVersion will introduce a new `Kind` alongside ZarfPackageConfig c
 
 Each ZarfComponentConfig declares exactly one component under the `component` field. If a user wants multiple variations of a component differentiated by flavor, OS, or architecture, they create one ZarfComponentConfig file per variation and set the `.component.target` field on each. View the ZarfComponentConfig schema in [design details](#zarf-component-config-schema).
 
-The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
+The component in a ZarfComponentConfig will be able to import another ZarfComponentConfig. Cyclical imports will result in an error. ZarfComponentConfig files will not have a default filename such as zarf.yaml. This will encourage users to give their files descriptive names and promote a flatter directory structure as users will not default to having a new folder for each component. ZarfComponentConfigs will be able to define their own values and valuesSchema.
 
-`.import.local` is a list of local file path references to ZarfComponentConfig files; directories are not accepted. `.import.remote` is a list of `oci://` URL references to remote component configs pulled at create time. All entries from both fields are combined when applying compatibility rules: when more than one entry is given, every referenced component must share the same name, and at most one of them must be compatible with the active package target (flavor, OS, architecture) at create time otherwise Zarf will error.
+`.import.local` is a list of local file path references to ZarfComponentConfig files; directories are not accepted. `.import.remote` is a list of `oci://` URL references to remote component configs pulled at create time. All entries from both fields are combined when applying compatibility rules: when more than one entry is given, every referenced component must share the same name, and at most one of them must be compatible with the active package target (flavor, OS, architecture) at create time, otherwise Zarf will error.
 
 The `zarf dev` commands that accept a directory containing a `zarf.yaml` (lint, inspect, and find-images) will accept component config files. For example, `zarf dev inspect definition my-component-config.yaml`.
 
@@ -255,7 +255,7 @@ The Zarf v1alpha1 schema allows for package templates during create using the ##
 
 The `.gen` extension will be used to easily discern between generated and included packages. It will also make it simple to ignore these files within Git repositories. When `zarf package create`, or any other relevant command, is run on a directory, it will first look for a `zarf.yaml`, then fall back to a `zarf.gen.yaml`.
 
-`zarf dev template` will have logic to follow local component imports. For any entry in `.import.local` whose `path` points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and rewrite the entry to `<base>.gen.yaml`. Users that prefer to template in separate steps may set their import path entries to `<base>.gen.yaml` directly. Zarf will template imports after the current file is finished templating, so a user will be able to template a value into an entry of `.import.local` and Zarf will template the resulting file.
+`zarf dev template` will have logic to follow local component imports. For any entry in `.import.local` whose `path` points to a file called `<base>.tpl.yaml`, Zarf will template the `<base>.tpl.yaml` file and rewrite the entry to `<base>.gen.yaml`. Users who prefer to template in separate steps may set their import path entries to `<base>.gen.yaml` directly. Zarf will template imports after the current file is finished templating, so a user will be able to template a value into an entry of `.import.local` and Zarf will template the resulting file.
 
 Package templates will be required to have a value; otherwise the command will fail.
 

From b69ee4d8dbb78eb9060ab7cf462ad6ed390501c1 Mon Sep 17 00:00:00 2001
From: Austin Abro <austinabro321@gmail.com>
Date: Tue, 19 May 2026 13:30:41 -0500
Subject: [PATCH 131/131] inconsistencies

Signed-off-by: Austin Abro <austinabro321@gmail.com>
---
 0051-v1beta1-schema/README.md |  2 +-
 0051-v1beta1-schema/zarf.yaml | 22 +++++++++++-----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md
index 0f91200..d64dbcd 100644
--- a/0051-v1beta1-schema/README.md
+++ b/0051-v1beta1-schema/README.md
@@ -173,7 +173,7 @@ If a package has these fields defined, then `zarf dev upgrade-schema` will error
 - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`.
 - `.components.[x].only.cluster.architecture` will be inlined to `.components.[x].target.architecture`. This is more accurate as the field checks the `.metadata.architecture` on create, rather than the cluster during deploy. Note that `.only` was renamed to `.target`. Since `.cluster.distro` will be removed, the `.cluster` parent field will be deleted. 
 - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, and `vendor` will be removed. `zarf dev upgrade-schema` will move these fields under `.metadata.annotations`, which is a generic map of strings.
-- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.after.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
+- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.onSuccess.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus-style readiness checks when `.wait.cluster.condition` is empty. See [wait changes](#wait-changes).
 - `.components.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes).
 - `.components.[x].images` will move from a list of strings to a list of objects. The `Image` object will have a required field, `name`, and an optional enum, `source`. Allowed values for `source` will be `daemon` and `registry`. Zarf will no longer fall back to pulling images from the Docker Daemon. During component imports, the merge strategy will change from a simple append to a merge based on `name`. `source` and any future fields will favor the base component value if set, and otherwise use the imported component value. 
 - `.components.[x].import.name` will be removed given that components will only be importable from component config files so there is not a name to select. See [ZarfComponentConfig](#zarfcomponentconfig).
diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml
index 4422671..6422510 100644
--- a/0051-v1beta1-schema/zarf.yaml
+++ b/0051-v1beta1-schema/zarf.yaml
@@ -1,4 +1,4 @@
-kind: ZarfInitConfig
+kind: ZarfPackageConfig
 apiVersion: zarf.dev/v1beta1
 metadata:
   name: everything-zarf-package
@@ -6,7 +6,7 @@ metadata:
   version: v1.0.0
   uncompressed: false
   architecture: amd64
-  annotations: # All of these are v1alpha1 fields that will be deprecated in favor of a choose your own adventure label map
+  annotations: # Most of these annotations are v1alpha1 fields that were removed in favor of a choose your own adventure map
     authors: cool-kidz
     documentation: https://my-package-documentation.com
     source: https://my-git-server/my-package
@@ -120,7 +120,7 @@ components:
           linux: sh
           windows: powershell
       before:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -146,7 +146,7 @@ components:
             address: github.com
             code: 200
       onSuccess:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -172,7 +172,7 @@ components:
             address: github.com
             code: 200
       onFailure:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -210,7 +210,7 @@ components:
           linux: sh
           windows: powershell
       before:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -236,7 +236,7 @@ components:
             address: github.com
             code: 200
       onSuccess:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -262,7 +262,7 @@ components:
             address: github.com
             code: 200
       onFailure:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -300,7 +300,7 @@ components:
           linux: sh
           windows: powershell
       before:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -326,7 +326,7 @@ components:
             address: github.com
             code: 200
       onSuccess:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir
@@ -352,7 +352,7 @@ components:
             address: github.com
             code: 200
       onFailure:
-      - mute: false
+      - silent: false
         maxTotalSeconds: 60
         retries: 0
         dir: dir