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

@@ -14,11 +14,16 @@ IgnoredScopes = code, tt, a, img
 mdx = md
 
 [*.{md,mdx}]
+TokenIgnores = (\{#[^}]+\})
 
 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/enterprise/updating-apps.mdx

@@ -16,7 +16,7 @@ The Admin Console only deploys new versions automatically if preflight checks pa
 
 Automatic updates have the following limitations:
 
-* Automatic updates are not supported for [Replicated Embedded Cluster](/vendor/embedded-overview) installations.
+* Automatic updates are not supported for [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview) installations.
 
 * Automatic updates are not supported for applications installed in air gap environments with no outbound internet access.
 

docs/intro-replicated.mdx

@@ -29,7 +29,7 @@ The following diagram demonstrates the process of using the Replicated Platform
 
 The diagram above shows an application that is packaged with the [**Replicated SDK**](/vendor/replicated-sdk-overview). The application is tested in clusters provisioned with the [**Replicated Compatibility Matrix (CMX)**](/vendor/testing-about), then added to a new release in the [**Vendor Portal**](/vendor/releases-about) using an automated CI/CD pipeline.
 
-The application is then installed by a customer ("Big Bank") on a VM. To install, the customer downloads their license, which grants proxy access to the application images through the [**Replicated proxy registry**](/vendor/private-images-about). They also download the installation assets for the [**Replicated Embedded Cluster**](/vendor/embedded-overview) installer.
+The application is then installed by a customer ("Big Bank") on a VM. To install, the customer downloads their license, which grants proxy access to the application images through the [**Replicated proxy registry**](/vendor/private-images-about). They also download the installation assets for the [**Replicated Embedded Cluster**](/embedded-cluster/v3/embedded-overview) installer.
 
 Embedded Cluster runs [**preflight checks**](/vendor/preflight-support-bundle-about) to verify that the environment meets the installation requirements, provisions a cluster on the VM, and installs [**Replicated KOTS**](intro-kots) in the cluster. KOTS provides an [**Admin Console**](intro-kots#kots-admin-console) where the customer enters application-specific configurations, runs application preflight checks, optionally joins nodes to the cluster, and then deploys the application. After installation, customers can manage both the application and the cluster from the Admin Console.
 
@@ -45,7 +45,7 @@ Replicated Embedded Cluster is a Kubernetes installer based on the open source K
 
 Additionally, each version of Embedded Cluster includes a specific version of [Replicated KOTS](#kots) that is installed in the cluster during installation. KOTS is used by Embedded Cluster to deploy the application and also provides the Admin Console UI where users can manage both the application and the cluster.
 
-For more information, see [Embedded Cluster Overview](/vendor/embedded-overview).
+For more information, see [Embedded Cluster Overview](/embedded-cluster/v3/embedded-overview).
 
 ### KOTS (Admin Console) {#kots}
 
@@ -169,9 +169,9 @@ Additionally, the Replicated proxy registry grants proxy access to private appli
 
 Applications distributed with the Replicated Platform can support multiple different installation methods from the same application release, helping you to meet your customers where they are. For example:
 
-* Customers who are not experienced with Kubernetes or who prefer to deploy to a dedicated cluster in their environment can install on a VM or bare metal server with the Replicated Embedded Cluster installer. For more information, see [Embedded Cluster Overview](/vendor/embedded-overview).
+* Customers who are not experienced with Kubernetes or who prefer to deploy to a dedicated cluster in their environment can install on a VM or bare metal server with the Replicated Embedded Cluster installer. For more information, see [Embedded Cluster Overview](/embedded-cluster/v3/embedded-overview).
 * Customers familiar with Kubernetes and Helm can install in their own existing cluster using the Helm CLI. For more information, see [Installing with Helm](/vendor/install-with-helm).
-* Customers installing into environments with limited or no outbound internet access (often referred to as air-gapped environments) can securely access and push images to their own internal registry, then install using Helm or a Replicated installer. For more information, see [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap) and [Installing and Updating with Helm in Air Gap Environments](/vendor/helm-install-airgap).
+* Customers installing into environments with limited or no outbound internet access (often referred to as air-gapped environments) can securely access and push images to their own internal registry, then install using Helm or a Replicated installer. For more information, see [Air Gap Installation with Embedded Cluster](/embedded-cluster/v3/installing-embedded-air-gap) and [Installing and Updating with Helm in Air Gap Environments](/vendor/helm-install-airgap).
 
 Additionally, to enhance the installation experience, the Enterprise Portal provides a customizable, web-based portal where your customers can view application install and update instructions, upload support bundles, view insights about their active and inactive instances, and more. For more information, see [About the Enteprise Portal](/vendor/enterprise-portal-about).
 

docs/intro.mdx

@@ -230,7 +230,7 @@ import clsx from "clsx";
         <div className={clsx("row", "browse-docs-links")}>
           <div className={clsx("col", "col--4")}>
             <div className="browse-docs-link-container">
-              <a href="/vendor/embedded-overview" className="browse-docs-link">
+              <a href="/embedded-cluster/v3/embedded-overview" className="browse-docs-link">
                 Overview
               </a>
               <p className="browse-docs-link-description">
@@ -241,7 +241,7 @@ import clsx from "clsx";
           </div>
           <div className={clsx("col", "col--4")}>
             <div className="browse-docs-link-container">
-              <a href="/reference/embedded-config" className="browse-docs-link">
+              <a href="/embedded-cluster/v3/embedded-config" className="browse-docs-link">
                 Embedded Cluster Config
               </a>
               <p className="browse-docs-link-description">
@@ -252,7 +252,7 @@ import clsx from "clsx";
           <div className={clsx("col", "col--4")}>
             <div className="browse-docs-link-container">
               <a
-                href="/enterprise/installing-embedded"
+                href="/embedded-cluster/v3/installing-embedded"
                 className="browse-docs-link"
               >
                 Online Installation with Embedded Cluster
@@ -265,7 +265,7 @@ import clsx from "clsx";
           <div className={clsx("col", "col--4")}>
             <div className="browse-docs-link-container">
               <a
-                href="/enterprise/installing-embedded-air-gap"
+                href="/embedded-cluster/v3/installing-embedded-air-gap"
                 className="browse-docs-link"
               >
                 Air Gap Installation with Embedded Cluster
@@ -278,7 +278,7 @@ import clsx from "clsx";
           <div className={clsx("col", "col--4")}>
             <div className="browse-docs-link-container">
               <a
-                href="/enterprise/updating-embedded"
+                href="/embedded-cluster/v3/updating-embedded"
                 className="browse-docs-link"
               >
                 Perform Updates with Embedded Cluster

docs/partials/configValues/_config-values-procedure.mdx

@@ -2,7 +2,7 @@ During installation, KOTS automatically generates a ConfigValues file and saves
 
 To get the ConfigValues file from an installed application instance:
 
-1. Install the target release in a development environment. You can either install the release with Replicated Embedded Cluster or install in an existing cluster with KOTS. For more information, see [Online Installation with Embedded Cluster](/enterprise/installing-embedded) or [Online Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster).
+1. Install the target release in a development environment. You can either install the release with Replicated Embedded Cluster or install in an existing cluster with KOTS. For more information, see [Online Installation with Embedded Cluster](/embedded-cluster/v3/installing-embedded) or [Online Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster).
 
 1. Depending on the installer that you used, do one of the following to get the ConfigValues for the installed instance:
 

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-cluster/v3/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
-```
+```