@intentius/chant-lexicon-k8s 0.41.20 → 0.44.1

package/dist/rules/flux002.ts

@@ -0,0 +1,77 @@
+/**
+ * FLUX002: Kustomization.spec.sourceRef must reference a declared source
+ *
+ * A Flux `Kustomization` names its source in `spec.sourceRef` — a
+ * `GitRepository`, `OCIRepository`, or `Bucket` the source-controller fetches.
+ * If the referenced source isn't declared in the build, the
+ * kustomize-controller waits on an artifact that never arrives and the
+ * Kustomization stalls. The bootstrap-created `flux-system` GitRepository
+ * always exists on a bootstrapped cluster, so a reference to it is never
+ * flagged — the Flux analogue of ARGO002's built-in `default` project.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+
+/** Source kinds the kustomize-controller can reconcile from. */
+const SOURCE_KINDS = ["GitRepository", "OCIRepository", "Bucket"] as const;
+
+/** The GitRepository `flux bootstrap` creates alongside the controllers. */
+const BOOTSTRAP_SOURCE_NAME = "flux-system";
+
+export const flux002: PostSynthCheck = {
+  id: "FLUX002",
+  description: "Kustomization.spec.sourceRef must reference a declared source (or the bootstrap flux-system repo)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+
+    // Declared sources, keyed "Kind/name". Namespace is deliberately ignored:
+    // an unset sourceRef.namespace resolves in the Kustomization's own, and
+    // the common estate keeps everything in flux-system anyway.
+    const declaredSources = new Set<string>();
+    for (const kind of SOURCE_KINDS) {
+      for (const source of manifestsOfKind(manifests, kind)) {
+        const name = source.metadata?.name;
+        if (typeof name === "string") declaredSources.add(`${kind}/${name}`);
+      }
+    }
+
+    for (const kustomization of manifestsOfKind(manifests, "Kustomization")) {
+      // Flux and kustomize.config.k8s.io share the kind name; only the Flux CR
+      // carries a sourceRef-bearing spec.
+      const apiVersion = kustomization.apiVersion;
+      if (typeof apiVersion === "string" && !apiVersion.startsWith("kustomize.toolkit.fluxcd.io/")) continue;
+
+      const name = kustomization.metadata?.name ?? "Kustomization";
+      const sourceRef = kustomization.spec?.sourceRef as
+        | { kind?: unknown; name?: unknown }
+        | undefined;
+
+      if (!sourceRef || typeof sourceRef.name !== "string" || sourceRef.name === "") {
+        diagnostics.push({
+          checkId: "FLUX002",
+          severity: "error",
+          message: `Kustomization "${name}" has no spec.sourceRef.name — the kustomize-controller cannot resolve a source.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+        continue;
+      }
+
+      const kind = typeof sourceRef.kind === "string" && sourceRef.kind !== "" ? sourceRef.kind : "GitRepository";
+      if (kind === "GitRepository" && sourceRef.name === BOOTSTRAP_SOURCE_NAME) continue;
+      if (declaredSources.has(`${kind}/${sourceRef.name}`)) continue;
+
+      diagnostics.push({
+        checkId: "FLUX002",
+        severity: "error",
+        message: `Kustomization "${name}" references ${kind} "${sourceRef.name}", which is not declared. Declare the source (e.g. FluxGitSource) or point sourceRef at the bootstrap flux-system repo.`,
+        entity: name,
+        lexicon: "k8s",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/flux003.ts

@@ -0,0 +1,75 @@
+/**
+ * FLUX003: Kustomization.spec.dependsOn entries should name declared Kustomizations
+ *
+ * `dependsOn` is Flux's reconcile-ordering edge: the Kustomization stays
+ * pending until every named Kustomization is ready. The names are plain
+ * strings with no referential integrity — a typo, or an entry left behind
+ * after a rename, stalls the app silently. This check joins each entry
+ * against the Kustomizations the build actually declares.
+ *
+ * It is a warning, not an error: estates legitimately split infra and apps
+ * across repos, so a dependency (say `cert-manager`) may be declared by a
+ * build this one never sees. A self-referencing entry is flagged too — Flux
+ * can never satisfy it.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+import type { K8sManifest } from "./k8s-helpers";
+
+/** Flux Kustomizations only — the kustomize.config.k8s.io kind shares the name. */
+function fluxKustomizations(manifests: K8sManifest[]): K8sManifest[] {
+  return manifestsOfKind(manifests, "Kustomization").filter((m) => {
+    const apiVersion = m.apiVersion;
+    return typeof apiVersion !== "string" || apiVersion.startsWith("kustomize.toolkit.fluxcd.io/");
+  });
+}
+
+export const flux003: PostSynthCheck = {
+  id: "FLUX003",
+  description: "Kustomization.spec.dependsOn entries should name Kustomizations declared in the build",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const kustomizations = fluxKustomizations(allManifests(ctx));
+
+    const declared = new Set(
+      kustomizations
+        .map((k) => k.metadata?.name)
+        .filter((n): n is string => typeof n === "string"),
+    );
+
+    for (const kustomization of kustomizations) {
+      const name = kustomization.metadata?.name ?? "Kustomization";
+      const dependsOn = kustomization.spec?.dependsOn;
+      if (!Array.isArray(dependsOn)) continue;
+
+      for (const entry of dependsOn) {
+        const depName = (entry as { name?: unknown } | null)?.name;
+        if (typeof depName !== "string" || depName === "") continue;
+
+        if (depName === name) {
+          diagnostics.push({
+            checkId: "FLUX003",
+            severity: "warning",
+            message: `Kustomization "${name}" depends on itself — Flux can never satisfy the edge and the app will not reconcile.`,
+            entity: name,
+            lexicon: "k8s",
+          });
+          continue;
+        }
+
+        if (declared.has(depName)) continue;
+
+        diagnostics.push({
+          checkId: "FLUX003",
+          severity: "warning",
+          message: `Kustomization "${name}" depends on Kustomization "${depName}", which nothing in the build declares — reconciliation stalls until it exists. Fix the name, or ignore if it is declared in another repo.`,
+          entity: name,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA6MlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA8I3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA8MlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA2K3B,CAAC"}

package/dist/skills/chant-k8s-flux.md

@@ -0,0 +1,162 @@
+---
+skill: chant-k8s-flux
+description: Flux CD composites for GitOps reconciliation — FluxGitSource + FluxAppFor, the one-source-many-apps shape, dependsOn ordering, the FLUX rules, and the flux-reconcile deploy step
+user-invocable: true
+---
+
+# Flux CD Composites
+
+Chant authors typed infrastructure into manifests. Flux continuously reconciles those manifests into a cluster from git. These composites are the opt-in bridge — the k8s lexicon itself stays runtime-agnostic and only emits YAML; nothing here is implied unless you reach for it.
+
+## The split
+
+| Layer | Owns | In Chant |
+|---|---|---|
+| **Chant** | Authoring typed infra → manifests, committed to git | the lexicons |
+| **Flux** | Continuously reconciling those manifests (source-controller fetches, kustomize-controller applies) | `FluxGitSource` / `FluxAppFor` |
+| **Chant again** | Reading convergence back | `flux-reconcile` deploy step, `chant components status --live` |
+
+Flux never learns Chant exists — it fetches a git path and applies what it finds there. Chant's job ends at emitting the manifests and the Flux CRs that point at them.
+
+## Prerequisites
+
+The Flux controllers must be installed in the target cluster before applying any Flux CRs:
+
+```bash
+kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v2.9.1/install.yaml
+kubectl -n flux-system wait deploy --all --for=condition=Available --timeout=180s
+```
+
+(Or `flux install` / `flux bootstrap` with the Flux CLI. `flux bootstrap` also creates a `flux-system` `GitRepository` — FLUX002 knows about it, see below.)
+
+## When to use which
+
+| Composite | Use case |
+|---|---|
+| `FluxGitSource` | Declare the git repo the source-controller fetches — **once per repo** |
+| `FluxAppFor` | One `Kustomization` reconciling one path out of a declared source — once per app |
+
+---
+
+## FluxGitSource — declare the repo once
+
+```typescript
+import { FluxGitSource } from "@intentius/chant-lexicon-k8s";
+
+export const source = FluxGitSource("home-chant", {
+  url: "https://github.com/jhgaylor/home-chant",
+  branch: "main",
+});
+```
+
+`FluxGitSource(name, options)` returns `{ gitRepository }` — a single `K8s::Flux::GitRepository` in `flux-system`. Options:
+
+- **`url`** (required) — the repo the source-controller fetches.
+- **`branch`** — defaults to `"main"`. **`tag`** pins a tag instead and wins over `branch`.
+- **`interval`** — fetch interval, default `"5m"`.
+- **`secretRef`** — name of the Secret holding git credentials, for private repos.
+- **`fluxNamespace`** — where the CR lives, default `"flux-system"`.
+
+> **FLUX001** — a hand-written `GitRepository` whose spec has a `url` but no `ref` is flagged: an unset `spec.ref` falls back to the `master` branch, which on most repos no longer exists, so the source stalls with a checkout error and every Kustomization downstream stalls too. `FluxGitSource` always emits a `ref` (branch or tag), so composite output is FLUX001-clean by construction.
+
+## FluxAppFor — one Kustomization per app
+
+```typescript
+import { FluxAppFor } from "@intentius/chant-lexicon-k8s";
+
+export const hello = FluxAppFor("hello-chant", {
+  source,                          // the FluxGitSource result above
+  path: "./apps/hello-chant/k8s",
+  targetNamespace: "default",
+  dependsOn: ["cert-manager", "traefik"],
+});
+```
+
+`FluxAppFor(target, options)` returns `{ kustomization }` — a single `K8s::Flux::Kustomization`. Defaults are taken from real Flux estates, not the docs:
+
+- **`interval`** — `"10m"` (the source polls at 5m; reconcile less often than you fetch).
+- **`prune: true`** — resources that disappear from the source are deleted.
+- **`wait: true`** — the Kustomization reports Ready only when the reconciled resources are ready.
+- **`targetNamespace`** — optional; sets `spec.targetNamespace` (kustomize-controller stamps it on every reconciled resource).
+- **`timeout`**, **`suspend`**, **`serviceAccountName`** — pass-throughs for the matching spec fields.
+
+### The source option
+
+`source` accepts three shapes:
+
+```typescript
+FluxAppFor("app", { source,                         path: "./apps/app" });  // FluxGitSource result
+FluxAppFor("app", { source: "flux-system",           path: "./apps/app" });  // name of an existing GitRepository
+FluxAppFor("app", { source: { kind: "OCIRepository", name: "images" }, path: "./apps/app" });  // explicit ref
+```
+
+The first is the normal case. The second targets a source declared elsewhere — typically the bootstrap-created `flux-system` repo. The third covers `OCIRepository` / `Bucket` sources.
+
+> **FLUX002** — every `Kustomization.spec.sourceRef` must name a source the build declares (`GitRepository`, `OCIRepository`, or `Bucket`), or the kustomize-controller waits forever on an artifact that never arrives. The bootstrap-created `flux-system` `GitRepository` is exempt — it always exists on a bootstrapped cluster, the Flux analogue of ARGO002's built-in `default` project.
+
+### One source, many apps
+
+The common estate shape is **one `GitRepository` shared by many `Kustomization`s** — a multi-app repo with one Kustomization per path. A `GitRepository` per app is the mistake the composite split makes hard: declare the source once, hand its result to every `FluxAppFor`.
+
+```typescript
+const source = FluxGitSource("infra", { url: "https://github.com/acme/infra" });
+
+export const platform = FluxAppFor("platform", { source, path: "./dist/platform" });
+export const api      = FluxAppFor("api",      { source, path: "./dist/apps/api", dependsOn: ["platform"] });
+export const web      = FluxAppFor("web",      { source, path: "./dist/apps/web", dependsOn: ["platform", "api"] });
+```
+
+### dependsOn — ordering as a validated name list
+
+`dependsOn` is a plain string list rendered to `spec.dependsOn`; the Kustomization stays pending until every named Kustomization is Ready. In raw YAML those names have no referential integrity — a typo, or an entry left behind after a rename, stalls the app silently.
+
+> **FLUX003** — every `dependsOn` entry is joined against the Kustomizations the build actually declares. An entry naming nothing is a warning (not an error — estates legitimately split infra and apps across repos, so `cert-manager` may be declared by a build this one never sees). A self-referencing entry is always flagged: Flux can never satisfy it.
+
+---
+
+## Deploying — the flux-reconcile step
+
+Applying `dist/flux.yaml` with `kubectl` works. For the component model, `fluxReconcile` is the typed deploy leaf (the sibling of `argo-app`):
+
+```typescript
+import { phase, type Component } from "@intentius/chant/components/component";
+import { fluxReconcile } from "@intentius/chant-lexicon-k8s/components";
+
+export const bootstrap: Component = {
+  name: "flux-bootstrap",
+  archetype: "service",
+  dependsOn: [],
+  deploy: [
+    phase("Reconcile", [
+      fluxReconcile({
+        manifest: "dist/flux.yaml",
+        stack: "my-estate",
+        noRollback: "server-side apply keeps no previous object state; the declared source is the restore path",
+      }),
+    ]),
+  ],
+};
+```
+
+What it does:
+
+1. **Applies** the Flux CRs through the same server-side apply `kubectl-apply` uses — ownership stamping, marker-scoped prune, stack labels all identical.
+2. **Waits for Ready, sources first.** A Kustomization cannot become Ready before its GitRepository has an artifact, so gating on `source.toolkit.fluxcd.io` kinds first surfaces a wedged clone as the source's error rather than a reconciler timeout downstream. The generic `waitForReady` handles the rest of the toolkit (kstatus-conformant), with fail-fast on wedge reasons like `BuildFailed` or `UpgradeFailed` from the readiness registry.
+3. **Refuses non-Flux manifests.** If the manifest applies no Flux CR at all, the step errors — a plain manifest belongs on `kubectl-apply`, and two things applying the same resources is the failure mode worth engineering against.
+
+It is a `needs-opt-out` capability (COMP003): every step needs `noRollback: "<reason>"`, a component `rollback` phase, or a sibling safety step — same posture as `kubectl-apply`, and for the same reason.
+
+## Reading convergence back
+
+The build stamps `app.kubernetes.io/managed-by: chant` and (with `ownership` configured) `chant.intentius.io/stack: <stack>` labels on every resource. Flux applies the manifests, but the labels travel with them — so `chant components status --live` attributes the running workloads to the stack through the k8s lexicon's label-selector read, regardless of who did the applying. Flux prunes by its own labels; chant observes by its own labels; neither needs the other's.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Kustomization stuck, no artifact | Source stalled — unset `spec.ref` fell back to `master` | Pin a branch/tag (FLUX001); `FluxGitSource` does this by default |
+| Kustomization waits forever | `sourceRef` names an undeclared source | Declare it with `FluxGitSource`, or point at the bootstrap `flux-system` repo (FLUX002) |
+| App pending, dependencies "not ready" | `dependsOn` names a Kustomization that doesn't exist (typo/rename) | Fix the name (FLUX003), or confirm the other repo declares it |
+| App pending forever, no error | `dependsOn` self-reference | Remove the self-edge (FLUX003 flags it) |
+| Resources deleted unexpectedly | `prune: true` (the default) and the path stopped emitting them | Intended GitOps behavior; pass `prune: false` to opt out |
+| `flux-reconcile` step errors immediately | Manifest contains no Flux CR | Use `kubectl-apply` for plain manifests |

package/dist/types/index.d.ts

@@ -2,6 +2,18 @@
 
 // --- Kubernetes Resource classes ---
 
+export declare class Addon {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** Spec provides information about the on-disk manifest backing this resource. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly uid: string;
+}
+
 export declare class Alert {
   constructor(props: {
     /** Standard object's metadata. */
@@ -920,6 +932,19 @@ export declare class FlowSchemaList {
   readonly uid: string;
 }
 
+export declare class FluxHelmChart {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** HelmChartSpec specifies the desired state of a Helm chart. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly status: Record<string, unknown>;
+  readonly uid: string;
+}
+
 export declare class FluxInstance {
   constructor(props: {
     /** Standard object's metadata. */
@@ -999,16 +1024,16 @@ export declare class GRPCRoute {
   readonly uid: string;
 }
 
-export declare class HelmChart {
+export declare class HelmChartConfig {
   constructor(props: {
     /** Standard object's metadata. */
     metadata?: ObjectMeta;
-    /** HelmChartSpec specifies the desired state of a Helm chart. */
+    /** HelmChartConfigSpec represents additional user-configurable details of an installed and configured Helm chart release.
+These fields are merged with or override the corresponding fields on the related HelmChart resource. */
     spec?: Record<string, unknown>;
   });
   readonly name: string;
   readonly namespace: string;
-  readonly status: Record<string, unknown>;
   readonly uid: string;
 }
 
@@ -1325,6 +1350,19 @@ export declare class JobList {
   readonly uid: string;
 }
 
+export declare class K3sHelmChart {
+  constructor(props: {
+    /** Standard object's metadata. */
+    metadata?: ObjectMeta;
+    /** HelmChartSpec represents the user-configurable details for installation and upgrade of a Helm chart release. */
+    spec?: Record<string, unknown>;
+  });
+  readonly name: string;
+  readonly namespace: string;
+  readonly status: Record<string, unknown>;
+  readonly uid: string;
+}
+
 export declare class Kustomization {
   constructor(props: {
     /** Standard object's metadata. */

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAuBvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAQpF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAuBvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAYpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.41.20",
+  "version": "0.44.1",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.41.5"
+    "@intentius/chant-k8s-client": "^0.44.1"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.41.20",
+    "@intentius/chant": "^0.44.1",
     "typescript": "^5.9.3"
   }
 }

package/src/api/classify.test.ts

@@ -93,6 +93,26 @@ describe("classifyApiFailure", () => {
     }
   });
 
+  test("the detail names the context the client read, when the failure carries it (#1488)", () => {
+    const err = status(500, "InternalError");
+    err.contextNote = 'context "k3d-kubemicrovm-local" (ambient; no k8s.profiles.local binding)';
+    const outcome = classifyApiFailure(err);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      expect(outcome.detail).toContain('context "k3d-kubemicrovm-local" (ambient; no k8s.profiles.local binding)');
+    }
+  });
+
+  test("the context note survives the one-line cap rather than truncating with the message (#1488)", () => {
+    const err = new K8sApiError(500, "InternalError", "x".repeat(500));
+    err.contextNote = 'context "prod-eks" (bound by k8s.profiles.prod.context)';
+    const outcome = classifyApiFailure(err);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      expect(outcome.detail.endsWith('context "prod-eks" (bound by k8s.profiles.prod.context)')).toBe(true);
+    }
+  });
+
   test("classification survives a duplicated copy of the client package", () => {
     // Discrimination is by `name`, not `instanceof`, so an error from a second
     // physical copy of the package in a consumer's tree still classifies.

package/src/api/classify.ts

@@ -47,6 +47,8 @@ interface ErrorLike {
   message?: string;
   statusCode?: number;
   reason?: string;
+  /** Which cluster the failing read talked to — stamped by the typed client (chant #1488). */
+  contextNote?: string;
 }
 
 function shapeOf(err: unknown): ErrorLike {
@@ -140,5 +142,10 @@ export const MISSING_CLIENT_DETAIL =
 function detailOf(err: unknown): string {
   const text = err instanceof Error ? err.message : String(err);
   const line = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? text.trim();
-  return line.length > 200 ? `${line.slice(0, 197)}...` : line;
+  const capped = line.length > 200 ? `${line.slice(0, 197)}...` : line;
+  // #1488 — a reason that does not say which cluster was read turned an
+  // ambient-context switch into an afternoon. The client stamps the context it
+  // resolved onto every failure; append it after the cap so it never truncates.
+  const note = shapeOf(err).contextNote;
+  return note ? `${capped} — ${note}` : capped;
 }

package/src/api/connect.ts

@@ -65,6 +65,7 @@ export const defaultK8sConnector: K8sConnector = async (options) => {
     const client = await createK8sClient({
       context: options.context,
       contextSource: "bound",
+      contextLabel: "explicit --context",
       ...options.client,
     });
     return { client, target: { context: options.context, source: "bound" } };
@@ -84,10 +85,19 @@ export const defaultK8sConnector: K8sConnector = async (options) => {
   // is supplied.
   const target = await resolveClusterTarget(config as Record<string, unknown>, options.environment, "k8s");
 
+  // #1488 — every failure the client throws names the cluster it read and how
+  // that cluster was selected, so a `read-failed` against the wrong context is
+  // legible from the reason alone.
+  const contextLabel =
+    target.source === "bound"
+      ? `bound by k8s.profiles.${options.environment}.context`
+      : `ambient; no k8s.profiles.${options.environment} binding`;
+
   const client = await createK8sClient({
     ...options.client,
     ...(target.context ? { context: target.context } : {}),
     contextSource: target.source,
+    contextLabel,
     ...(execAllowlist ? { execAllowlist } : {}),
   });
   return { client, target };

package/src/codegen/docs.ts

@@ -409,6 +409,16 @@ Quality checks for the [Argo CD composites](/chant/lexicons/k8s/argo-composites/
 | ARGO004 | \`ApplicationSet\` template doesn't scope to a single static \`AppProject\` |
 | ARGO005 | \`Application\` \`source.path\` doesn't resolve to a directory (warn) |
 
+### Flux
+
+Quality checks for the [Flux composites](/chant/lexicons/k8s/flux-composites/) (\`FluxGitSource\` / \`FluxAppFor\`). FLUX001 is declarative (source AST); FLUX002/003 are post-synth (cross-resource).
+
+| Rule | Description |
+|------|-------------|
+| FLUX001 | \`GitRepository\` has no \`spec.ref\` pin — Flux falls back to the \`master\` branch |
+| FLUX002 | \`Kustomization.spec.sourceRef\` references an undeclared source (the bootstrap \`flux-system\` repo is exempt) |
+| FLUX003 | \`Kustomization.spec.dependsOn\` names a \`Kustomization\` nothing in the build declares, or itself (warn) |
+
 ## Running lint
 
 \`\`\`bash
@@ -1160,6 +1170,7 @@ The lexicon also provides MCP (Model Context Protocol) tools and resources:
       },
       { label: "CRD-Generated Classes", slug: "crd-classes" },
       { label: "Argo CD Composites", slug: "argo-composites" },
+      { label: "Flux Composites", slug: "flux-composites" },
       {
         label: "Vendor Composites",
         items: [