WIP: Embedded Cluster v3

.claude/skills/vale-prose-review/SKILL.md

@@ -56,6 +56,8 @@ Do not apply prose fixes to:
 
 Vale sometimes flags these; ignore those warnings.
 
+**Exception — markdown inside HTML tables:** When `Vale.Spelling` flags a word like `_Using` inside an HTML `<td>` or `<p>` element, the cause is markdown italic syntax (`_text_`) used inside raw HTML. Do NOT add `_Using` to an accept list. Instead, convert the markdown formatting to HTML (`_foo_` → `<em>foo</em>`). See `references/vale-rules.md` for details.
+
 ### Step 5: Verify
 
 After making all changes, do a quick pass to confirm:
@@ -85,7 +87,7 @@ See `references/vale-rules.md` for full fix patterns, before/after examples, and
 
 **`Replicated.PositionalLanguage`** — Replace "above/below" with "the following" or a section link; replace directional "right/left" with "the following" or a UI element name.
 
-**`Replicated.Headings`** — Apply sentence case: lowercase all words except the first word and proper nouns (product names, trademarks).
+**`Replicated.Headings`** — Apply sentence case, with three exceptions: (1) **Skip entirely** when the heading IS a CLI command name or YAML field name (e.g., `# install (Beta)`, `## helmCharts`) — those follow the thing's own casing conventions. (2) **Parentheticals reset sentence case** — `(Beta)` is correct, not `(beta)`. (3) **Kubernetes custom resource kind names stay capitalized** — `Preflight`, `SupportBundle`, `Config`, `HelmChart` are proper names; check context to confirm the word refers to a `kind:` value before lowercasing. See `references/vale-rules.md` for full patterns.
 
 **`Replicated.WordsToAvoid`** — Remove "easy/easily", "simple/simply", "just" (when minimizing). Rephrase or omit.
 
@@ -94,3 +96,4 @@ See `references/vale-rules.md` for full fix patterns, before/after examples, and
 ## Additional Resources
 
 - **`references/vale-rules.md`** — Detailed fix patterns, edge cases, and examples for every common Replicated vale rule
+- **`README.md` (repo root)** — The Replicated Docs style guide lives in the "Style Guide" section of this file. Read it when deciding how to rewrite a flagged sentence, choose word alternatives, or apply formatting conventions. This is the authoritative source — do not rely on cached knowledge of its contents.

.claude/skills/vale-prose-review/references/vale-rules.md

@@ -28,6 +28,19 @@ Fix if the flagged word is a genuine misspelling. Vale flags these as errors, so
 - Flagged words inside inline code or code blocks
 - Acronyms in YAML frontmatter keys
 
+### Markdown formatting inside HTML tables
+
+When a file uses HTML `<table>`/`<td>`/`<p>` tags and the cell content contains markdown italic syntax (e.g., `_Using Embedded Cluster_`), vale treats the leading underscore as part of a word and flags `_Using` as a misspelling.
+
+**Do NOT add these to an accept list.** The fix is to convert the markdown formatting inside the HTML element to its HTML equivalent:
+
+| Before (markdown inside HTML) | After (HTML formatting) |
+|---|---|
+| `_Using Embedded Cluster_` | `<em>Using Embedded Cluster</em>` |
+| `**important**` | `<strong>important</strong>` |
+
+Apply this fix to the specific cell content where the flag appears. Other cells in the same table that use plain text are fine as-is.
+
 ---
 
 ## Replicated.Passive (suggestion)
@@ -101,6 +114,43 @@ Avoid directional and spatial language that assumes a page layout. Users may be
 
 Headings should use sentence case: capitalize only the first word and proper nouns.
 
+### Skip this rule entirely for reference page headings
+
+Do NOT apply sentence case to headings that are the exact name of a CLI command, YAML field, or other code identifier. These headings document the thing itself, so their capitalization is determined by the thing's own conventions, not sentence case.
+
+**Skip examples (leave unchanged):**
+- `# install (Beta)` — CLI command name; do not capitalize "install"
+- `# create-join-bundle (Beta)` — CLI command name
+- `### helmCharts` — YAML field name; do not change to `### HelmCharts`
+- `#### roles.controller` — dotted YAML field path
+- `## metadata` — YAML field name
+- `## unsupportedOverrides` — YAML field name
+
+### Parentheticals reset sentence case
+
+A parenthetical like `(Beta)` or `(Preview)` opens a new "sentence" within the heading. Capitalize the first word inside the parenthetical.
+
+- `(Beta)` is correct — **not** `(beta)`
+- `(Preview)` is correct — **not** `(preview)`
+- `(Deprecated)` is correct — **not** `(deprecated)`
+
+### Kubernetes custom resource kinds — always capitalize
+
+Custom resource kind names are proper names and must remain capitalized wherever they appear in headings, even mid-sentence. The key examples in Replicated docs:
+
+- `Preflight`
+- `SupportBundle`
+- `Config`
+- `HelmChart`
+
+**How to decide:** Look at the surrounding context. If the page or section is about a Kubernetes custom resource and the word refers to its `kind:` value, keep it capitalized. If the word is used in a different sense (for example, `config` as a generic noun, or `install` as a CLI command), lowercase it per the normal rules.
+
+**Examples:**
+- `## About the Preflight custom resource` — `Preflight` is the kind name, keep capital P
+- `## Configure your HelmChart` — `HelmChart` is the kind name, keep capital H
+- `## Embedded Cluster Config` — `Config` is the kind name (`kind: Config`), keep capital C
+- `## Override the k0s config` — `config` here is a generic noun referring to a k0s configuration file, lowercase is correct
+
 ### What to capitalize (proper nouns and trademarks)
 
 - Replicated product names: Embedded Cluster, KOTS, Vendor Portal, Enterprise Portal, Compatibility Matrix, Replicated SDK, Admin Console, Replicated CLI
@@ -109,17 +159,19 @@ Headings should use sentence case: capitalize only the first word and proper nou
 
 ### What to lowercase
 
-- Descriptive words that aren't proper names: "matrix" (when not a product name), "lifecycle", "overview", "portal" (when standalone), "guide", "about"
-- Status/qualifier words in parentheses: "(beta)", "(preview)", "(deprecated)"
+- Descriptive words that aren't proper names: "config", "overview", "lifecycle", "portal" (when standalone), "guide", "about"
+- Capitalized common words mid-heading: "Matrix" → "matrix" (when not a product name), "Values" → "values", "Built-In" → "built-in"
 
 ### Examples
 
 | Before | After |
 |---|---|
 | `### Compatibility Matrix` | `### Compatibility matrix` |
-| `### Enterprise Portal (Beta)` | `### Enterprise Portal (beta)` |
+| `### Enterprise Portal (Beta)` | `### Enterprise Portal (Beta)` ← keep capital B |
 | `## Commercial Software Distribution Lifecycle` | `## Commercial software distribution lifecycle` |
 | `### Vendor Portal Overview` | `### Vendor Portal overview` |
+| `# install (Beta)` | `# install (Beta)` ← CLI command, do not change |
+| `### helmCharts` | `### helmCharts` ← YAML field, do not change |
 
 **Note:** Only headings are subject to this rule. Body text references to product names keep their standard capitalization.
 

.vale.ini

@@ -19,6 +19,10 @@ BasedOnStyles = Vale, Replicated
 
 Vale.Terms = NO
 
+# Don't lint .claude skill/memory files
+[.claude/**]
+BasedOnStyles =
+
 # Don't lint CLI docs
 [docs/reference/kots-cli-*]
 BasedOnStyles =

docs/partials/embedded-cluster/_proxy-install-limitations.mdx

@@ -1,5 +1,5 @@
 **Limitations:**
 
-* If any of your [Helm extensions](/reference/embedded-config#extensions) make requests to the internet, the given charts need to be manually configured so that those requests are made to the user-supplied proxy server instead. Typically, this requires updating the Helm values to set HTTP proxy, HTTPS proxy, and no proxy. Note that this limitation applies only to network requests made by your Helm extensions. The proxy settings supplied to the install command are used to pull the containers required to run your Helm extensions.
+* If any of your [Helm extensions](embedded-config#extensions) make requests to the internet, the given charts need to be manually configured so that those requests are made to the user-supplied proxy server instead. Typically, this requires updating the Helm values to set HTTP proxy, HTTPS proxy, and no proxy. Note that this limitation applies only to network requests made by your Helm extensions. The proxy settings supplied to the install command are used to pull the containers required to run your Helm extensions.
 
 * Proxy settings cannot be changed after installation or during upgrade.

docs/partials/embedded-cluster/_shell-command.mdx

@@ -1,6 +1,6 @@
 To access the cluster and use other included binaries:
 
-1. SSH onto a controller node.
+1. SSH into a controller node.
 
      :::note
      You cannot run the `shell` command on worker nodes.

docs/partials/embedded-cluster/_warning-do-not-downgrade.mdx

@@ -1,3 +1,3 @@
 :::important
-Don't downgrade the Embedded Cluster version or the Kubernetes version. Also, only increase the Kubernetes version by one minor version at a time. For more information, see [Limitations](/vendor/embedded-overview#ec-limitations) in _Embedded Cluster Overview_.
+Don't downgrade the Embedded Cluster version or the Kubernetes version. Also, only increase the Kubernetes version by one minor version at a time. For more information, see [Limitations](embedded-overview#ec-limitations) in _Embedded Cluster Overview_.
 :::

docs/partials/embedded-cluster/_definition.mdx → docs/partials/embedded-cluster/v2/_definition.mdx

@@ -1,3 +1,3 @@
 Replicated Embedded Cluster allows you to distribute a Kubernetes cluster and your application together as a single appliance, making it easy for enterprise users to install, update, and manage the application and the cluster in tandem. Embedded Cluster is based on the open source Kubernetes distribution k0s. For more information, see the [k0s documentation](https://docs.k0sproject.io/stable/).
 
-For software vendors, Embedded Cluster provides a Config for defining characteristics of the cluster that will be created in the customer environment. Additionally, each version of Embedded Cluster includes a specific version of Replicated KOTS, ensuring compatibility between KOTS and the cluster. For enterprise users, cluster updates are done automatically at the same time as application updates, allowing users to more easily keep the cluster up-to-date without needing to use kubectl.
+For software vendors, Embedded Cluster provides a Config for defining characteristics of the cluster that will be created in the customer environment. Additionally, each version of Embedded Cluster includes a specific version of Replicated KOTS, ensuring compatibility between KOTS and the cluster. For enterprise users, cluster updates are done automatically at the same time as application updates, allowing users to more easily keep the cluster up-to-date without needing to use kubectl.

docs/partials/embedded-cluster/_ec-config.mdx → docs/partials/embedded-cluster/v2/_ec-config.mdx

@@ -3,4 +3,4 @@ apiVersion: embeddedcluster.replicated.com/v1beta1
 kind: Config
 spec:
   version: 2.13.5+k8s-1.33
-```
+```

docs/partials/install/_ec-prereqs.mdx → docs/partials/embedded-cluster/v2/_ec-prereqs.mdx

@@ -1,5 +1,5 @@
-* Ensure that your installation environment meets the Embedded Cluster requirements. See [Embedded Cluster Requirements](/enterprise/installing-embedded-requirements).
+* Ensure that your installation environment meets the Embedded Cluster requirements. See [Embedded Cluster Requirements](/embedded-cluster/v2/installing-embedded-requirements).
 
-* The application release that you want to install must include an [Embedded Cluster Config](/reference/embedded-config).
+* The application release that you want to install must include an [Embedded Cluster Config](/embedded-cluster/v2/embedded-config).
 
-* The license used to install must have the **Embedded Cluster Enabled** license field enabled. See [Create and Manage Customers](/vendor/releases-creating-customer).
+* The license used to install must have the **Embedded Cluster Enabled** license field enabled. See [Create and Manage Customers](/vendor/releases-creating-customer).

docs/partials/embedded-cluster/_multi-node-ha-arch.mdx → docs/partials/embedded-cluster/v2/_multi-node-ha-arch.mdx

@@ -11,4 +11,4 @@ As shown in the diagram above, in HA installations with Embedded Cluster:
 * For installations that include disaster recovery, the Velero pod is deployed on one node. The Velero Node Agent runs on each node in the cluster. The Node Agent is a Kubernetes DaemonSet that performs backup and restore tasks such as creating snapshots and transferring data during restores.
 * For air gap installations, two replicas of the air gap image registry are deployed.
 
-Any Helm [`extensions`](/reference/embedded-config#extensions) that you include in the Embedded Cluster Config are installed in the cluster depending on the given chart and whether or not it is configured to be deployed with high availability.
+Any Helm [`extensions`](embedded-config#extensions) that you include in the Embedded Cluster Config are installed in the cluster depending on the given chart and whether or not it is configured to be deployed with high availability.

docs/partials/embedded-cluster/_port-reqs.mdx → docs/partials/embedded-cluster/v2/_port-reqs.mdx

@@ -34,10 +34,10 @@ The KOTS Admin Console requires that port 30000/TCP is open and available. Creat
 
 Additionally, port 30000 must be accessible by nodes joining the cluster.
 
-If port 30000 is occupied, you can select a different port for the Admin Console during installation. For more information, see [install](/reference/embedded-cluster-install).
+If port 30000 is occupied, you can select a different port for the Admin Console during installation. For more information, see [install](/embedded-cluster/v2/embedded-cluster-install).
 
 #### LAM port
 
 The Local Artifact Mirror (LAM) requires that port 50000/TCP is open and available.
 
-If port 50000 is occupied, you can select a different port for the LAM during installation. For more information, see [install](/reference/embedded-cluster-install).
+If port 50000 is occupied, you can select a different port for the LAM during installation. For more information, see [install](/embedded-cluster/v2/embedded-cluster-install).

docs/partials/embedded-cluster/_requirements.mdx → docs/partials/embedded-cluster/v2/_requirements.mdx

@@ -10,7 +10,7 @@
 
 * The user performing the installation must have root access to the machine, such as with `sudo`.
 
-* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/reference/embedded-cluster-install).
+* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/embedded-cluster/v2/embedded-cluster-install).
 
    Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations:
 

docs/partials/embedded-cluster/_update-air-gap-admin-console.mdx → docs/partials/embedded-cluster/v2/_update-air-gap-admin-console.mdx

@@ -3,7 +3,7 @@
    ```bash
     curl -f https://replicated.app/embedded/APP_SLUG/CHANNEL_SLUG?airgap=true -H "Authorization: LICENSE_ID" -o APP_SLUG-CHANNEL_SLUG.tgz
    ```
-   For more information, see [Install](/enterprise/installing-embedded-air-gap#install).
+   For more information, see [Install](installing-embedded-air-gap#install).
 
 1. Untar the tarball. For example:
 
@@ -38,4 +38,4 @@
 
    ![Confirmation screen in the upgrade wizard](/images/ec-upgrade-wizard-confirm.png)
 
-   [View a larger version of this image](/images/ec-upgrade-wizard-confirm.png)
+   [View a larger version of this image](/images/ec-upgrade-wizard-confirm.png)

docs/partials/embedded-cluster/_update-air-gap-cli.mdx → docs/partials/embedded-cluster/v2/_update-air-gap-cli.mdx

@@ -4,7 +4,7 @@
     curl -f https://replicated.app/embedded/APP_SLUG/CHANNEL_SLUG?airgap=true -H "Authorization: LICENSE_ID" -o APP_SLUG-CHANNEL_SLUG.tgz
    ```
 
-   For more information, see [Install](/enterprise/installing-embedded-air-gap#install).
+   For more information, see [Install](installing-embedded-air-gap#install).
 
 1. Untar the tarball. For example:
 
@@ -47,4 +47,4 @@
 
    ![Confirmation screen in the upgrade wizard](/images/ec-upgrade-wizard-confirm.png)
 
-   [View a larger version of this image](/images/ec-upgrade-wizard-confirm.png)
+   [View a larger version of this image](/images/ec-upgrade-wizard-confirm.png)

docs/partials/embedded-cluster/_update-air-gap-overview.mdx → docs/partials/embedded-cluster/v2/_update-air-gap-overview.mdx

@@ -1,3 +1,3 @@
 To upgrade an installation, new air gap bundles can be uploaded to the Admin Console from the browser or with the Embedded Cluster binary from the command line.
 
-Using the binary is faster and allows the user to download the air gap bundle directly to the machine where the Embedded Cluster is running. Using the browser is slower because the user must download the air gap bundle to a machine with a browser, then upload that bundle to the Admin Console, and then the Admin Console can process it.
+Using the binary is faster and allows the user to download the air gap bundle directly to the machine where the Embedded Cluster is running. Using the browser is slower because the user must download the air gap bundle to a machine with a browser, then upload that bundle to the Admin Console, and then the Admin Console can process it.

docs/partials/embedded-cluster/_update-overview.mdx → docs/partials/embedded-cluster/v2/_update-overview.mdx

@@ -4,4 +4,4 @@ When you deploy a new version, any changes to the cluster are deployed first. Th
 
 Any changes made to the Embedded Cluster Config, including changes to the Embedded Cluster version, Helm extensions, and unsupported overrides, trigger a cluster update.
 
-When performing an upgrade with Embedded Cluster, the user is able to change the application config before deploying the new version. Additionally, the user's license is synced automatically. Users can also make config changes and sync their license outside of performing an update. This requires deploying a new version to apply the config change or license sync.
+When performing an upgrade with Embedded Cluster, the user is able to change the application config before deploying the new version. Additionally, the user's license is synced automatically. Users can also make config changes and sync their license outside of performing an update. This requires deploying a new version to apply the config change or license sync.

docs/partials/embedded-cluster/v3/_definition.mdx

@@ -0,0 +1,5 @@
+Replicated Embedded Cluster allows you to distribute a Kubernetes cluster and your application together as a single appliance, making it easy for enterprise users to install, update, and manage the application and the cluster in tandem. Embedded Cluster is based on the open source Kubernetes distribution k0s. For more information, see the [k0s documentation](https://docs.k0sproject.io/stable/).
+
+Software vendors can configure the Embedded Cluster Config manifest to define characteristics of the cluster and the installation. For example, you can add optional Helm extensions to deploy components in the cluster before Embedded Cluster installs your application.
+
+For enterprise users, Embedded Cluster provides a built-in UI that guides users through installation and upgrades. Additionally, Embedded Cluster automatically updates the cluster infrastructure at the same time as application updates, allowing users to more easily keep the cluster up-to-date without needing to use kubectl.

docs/partials/embedded-cluster/v3/_ec-config.mdx

@@ -0,0 +1,6 @@
+```yaml
+apiVersion: embeddedcluster.replicated.com/v1beta1
+kind: Config
+spec:
+  version: 3.0.0-alpha-26+k8s-1.34
+```

docs/partials/embedded-cluster/v3/_ec-prereqs.mdx

@@ -0,0 +1,5 @@
+* Ensure that your installation environment meets the Embedded Cluster requirements. See [Embedded Cluster Requirements](/embedded-cluster/v3/installing-embedded-requirements).
+
+* The application release that you want to install must include an [Embedded Cluster Config](/embedded-cluster/v3/embedded-config).
+
+* The license used to install must have the **Embedded Cluster Enabled** license field enabled. See [Create and Manage Customers](/vendor/releases-creating-customer).

docs/partials/embedded-cluster/v3/_generate-bundle-ec.mdx

@@ -0,0 +1,19 @@
+### Generate a support bundle
+
+The `support-bundle` command uses the default Embedded Cluster support bundle spec to collect both cluster- and host-level information. It also automatically includes any application-specific support bundle specs in the generated bundle. 
+
+To generate a support bundle:
+
+1. SSH onto a controller node.
+
+   :::note
+   You can SSH onto a worker node to generate a support bundle that contains information specific to that node. However, when run on a worker node, the `support-bundle` command does not capture cluster-wide information.
+   :::
+
+1. Run the following command:
+
+   ```bash
+   sudo ./APP_SLUG support-bundle
+   ```
+
+   Where `APP_SLUG` is the unique slug for the application.