@intentius/behold 0.4.1 → 0.6.0

package/README.md

@@ -28,6 +28,10 @@ npx @intentius/behold demo            # copies the example to ./behold-demo, ins
 ```
 
 The copied project is yours: edit its source and watch the graph change live.
+There's a whole catalog — `behold demo --list` names the rest (`behold demo
+k8s` stands the same loop up on a throwaway k3d cluster: runtime Pods, field
+ownership). Every loaded demo lands in the panel's recents, so switching
+between them is the Scope tab.
 
 Already have a chant project?
 

package/demos.json

@@ -0,0 +1,39 @@
+{
+  "demos": [
+    {
+      "name": "writes",
+      "description": "One S3 bucket + policy on a local Floci emulator — blue to green in five minutes. The default.",
+      "source": "bundled",
+      "dir": "example-writes",
+      "requires": ["docker"],
+      "serve": { "local": true, "env": "prod" }
+    },
+    {
+      "name": "k8s",
+      "description": "An nginx Deployment + Service on a throwaway k3d cluster — runtime children (Pods), field ownership, honest unobserved. Cluster persists across runs; scripts/local/local-down.sh removes it.",
+      "source": "bundled",
+      "dir": "example-k8s",
+      "requires": ["docker", "k3d", "kubectl"],
+      "setup": "bash scripts/local/local-up.sh",
+      "serve": { "local": true, "env": "local" }
+    },
+    {
+      "name": "flux-estate",
+      "description": "A GitOps estate: a Flux control plane (GitRepository + Kustomizations) plus two app projects, served as one composed estate — cross-stack sourceRef edges, estate-wide drift, and the namespace-mismatch note on purpose (app-b uses targetNamespace). k3d + Flux, no cloud. scripts/estate-down.sh removes the cluster.",
+      "source": "bundled",
+      "dir": "example-flux-estate",
+      "requires": ["docker", "k3d", "kubectl"],
+      "setup": "bash scripts/estate-up.sh",
+      "serve": { "env": "local", "dirs": ["control-plane", "app-a", "app-b"] }
+    },
+    {
+      "name": "fountain",
+      "description": "The mature estate: self-hosted fountain (a real app) on a throwaway k3d cluster — tiers (try the ha tier picker), seams, drift, runtime Pods. Clones INTENTIUS/fountain-ops; ~5 minutes, mostly image pulls. `just down` in the clone removes the cluster.",
+      "source": "git",
+      "repo": "https://github.com/INTENTIUS/fountain-ops",
+      "requires": ["docker", "k3d", "kubectl", "jq", "just"],
+      "setup": "just up",
+      "serve": { "env": "local" }
+    }
+  ]
+}

package/dist/cli.js

@@ -1,7 +1,7 @@
 // src/cli.ts
-import { resolve as resolve3, dirname as dirname5, join as join12, relative as relative2, sep } from "node:path";
+import { resolve as resolve3, dirname as dirname5, join as join13, relative as relative2, sep } from "node:path";
 import { realpathSync, existsSync as existsSync10, cpSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/server.ts
@@ -2593,7 +2593,7 @@ function namespaceMismatchNote(nodes) {
   const k8s = nodes.filter((n) => n?.lexicon === "k8s");
   if (k8s.length === 0) return void 0;
   const pending = k8s.filter((n) => n.attrs?._status === "accent" && !CLUSTER_SCOPED.has(n.kind ?? ""));
-  if (pending.length < 3) return void 0;
+  if (pending.length < 2) return void 0;
   if (pending.some((n) => typeof n.attrs?.metadata?.namespace === "string" && n.attrs.metadata.namespace)) return void 0;
   if (!k8s.some((n) => n.attrs?._status === "good")) return void 0;
   return `${pending.length} pending k8s objects declare no metadata.namespace \u2014 if a controller stamps it at apply time (e.g. Flux's targetNamespace), the live read looked in "default", not where they run`;
@@ -4611,6 +4611,9 @@ async function startServer(cfg) {
       );
     }
   }
+  for (const dir of cfg.projectDirs ?? [cfg.projectDir]) {
+    if (existsSync9(join10(dir, "chant.config.ts"))) addRecent(dir);
+  }
   const broadcaster = new Broadcaster();
   const frames = new FrameBuffer();
   const runner = new OpRunner({
@@ -4714,9 +4717,45 @@ async function startServer(cfg) {
   });
 }
 
+// src/demos.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+import { join as join11 } from "node:path";
+import { spawnSync } from "node:child_process";
+function loadDemoRegistry(pkgRoot) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync8(join11(pkgRoot, "demos.json"), "utf8"));
+  } catch {
+    return [];
+  }
+  const list = raw?.demos;
+  if (!Array.isArray(list)) return [];
+  return list.filter((e) => {
+    const d = e;
+    if (!d || typeof d.name !== "string" || !d.name || typeof d.description !== "string") return false;
+    if (d.source === "bundled") {
+      if (typeof d.dir !== "string" || !d.dir) return false;
+    } else if (d.source === "git") {
+      if (typeof d.repo !== "string" || !d.repo) return false;
+    } else {
+      return false;
+    }
+    if (!Array.isArray(d.requires) || d.requires.some((r) => typeof r !== "string")) return false;
+    if (!d.serve || typeof d.serve !== "object") return false;
+    if (d.serve.dirs !== void 0 && (!Array.isArray(d.serve.dirs) || d.serve.dirs.some((x) => typeof x !== "string") || !d.serve.dirs.length))
+      return false;
+    return true;
+  });
+}
+function missingRequirements(entry) {
+  const bins = entry.source === "git" && !entry.requires.includes("git") ? [...entry.requires, "git"] : entry.requires;
+  const finder = process.platform === "win32" ? "where" : "which";
+  return bins.filter((bin) => spawnSync(finder, [bin], { stdio: "ignore" }).status !== 0);
+}
+
 // src/export.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "node:fs";
-import { join as join11, dirname as dirname4, basename } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync9, readdirSync as readdirSync4 } from "node:fs";
+import { join as join12, dirname as dirname4, basename } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var LENS_PARAMS = ["components", "detail", "env", "logical", "radial", "tier"];
 function canonicalKey(path, params) {
@@ -4764,7 +4803,7 @@ function captureKeys(axes) {
   return [...keys];
 }
 function webDir() {
-  return join11(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
+  return join12(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
 }
 function workerName(project, override) {
   const raw = override ?? `behold-${basename(project)}`;
@@ -4775,7 +4814,7 @@ async function runExport(cfg, outDir, opts = {}) {
   const app = createApp(cfg);
   const proj = await (await app.request("/api/project")).json();
   const axes = { environments: proj.environments ?? [], tiers: proj.tiers ?? [] };
-  const snapDir = join11(outDir, "snapshots");
+  const snapDir = join12(outDir, "snapshots");
   mkdirSync2(snapDir, { recursive: true });
   const keyToFile = {};
   let ok = 0;
@@ -4784,7 +4823,7 @@ async function runExport(cfg, outDir, opts = {}) {
     const res = await app.request(key);
     const body = await res.text();
     const file = slug(key);
-    writeFileSync2(join11(snapDir, file), body);
+    writeFileSync2(join12(snapDir, file), body);
     keyToFile[key] = `snapshots/${file}`;
     if (res.ok) ok++;
     else failed++;
@@ -4796,21 +4835,21 @@ async function runExport(cfg, outDir, opts = {}) {
     axes,
     keyToFile
   };
-  writeFileSync2(join11(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-  const html = readFileSync8(join11(webDir(), "index.html"), "utf8").replace(
+  writeFileSync2(join12(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  const html = readFileSync9(join12(webDir(), "index.html"), "utf8").replace(
     /<\/head>/i,
     `  <script>window.__BEHOLD_STATIC__ = true;</script>
   </head>`
   );
-  writeFileSync2(join11(outDir, "index.html"), html);
+  writeFileSync2(join12(outDir, "index.html"), html);
   for (const f of readdirSync4(webDir())) {
     if (f === "index.html") continue;
-    copyFileSync(join11(webDir(), f), join11(outDir, f));
+    copyFileSync(join12(webDir(), f), join12(outDir, f));
   }
-  writeFileSync2(join11(outDir, "README.md"), BUNDLE_README);
+  writeFileSync2(join12(outDir, "README.md"), BUNDLE_README);
   const name = workerName(cfg.projectDir, opts.name);
   writeFileSync2(
-    join11(outDir, "wrangler.jsonc"),
+    join12(outDir, "wrangler.jsonc"),
     JSON.stringify(
       { $schema: "node_modules/wrangler/config-schema.json", name, compatibility_date: "2025-06-01", assets: { directory: "." } },
       null,
@@ -4861,17 +4900,20 @@ It's just files \u2014 GitHub Pages, S3, nginx, or Cloudflare Pages
 var USAGE = `behold \u2014 a live control plane on chant (read-only core)
 
 Usage:
-  behold demo [target-dir] [--port <n>]
+  behold demo [name] [target-dir] [--port <n>] [--list]
   behold preview [project-dir] [--port <n>] [--emulator]
   behold export [project-dir] [--out <dir>] [--env <name>] [--name <worker>] [--emulator]
   behold serve <project-dir\u2026> [--port <n>] [--env <name>] [--poll <secs>] [--local]
 
-  demo    The five-minute path from npm \u2014 no chant project needed. Copies the
-          bundled example (an S3 bucket + policy) into ./behold-demo (or
-          [target-dir]), installs its dependencies, and serves it against a
-          local emulator: blue = declared, click Deploy, watch it turn green.
-          Needs Docker. The copy is yours \u2014 edit its source and watch the
-          graph change live.
+  demo    The five-minute path from npm \u2014 no chant project needed. A catalog
+          of demo estates (behold demo --list): bundled ones copy out of the
+          package into a directory that's yours to edit; git ones shallow-
+          clone a public estate. Bare \`behold demo\` is the AWS example \u2014 an
+          S3 bucket + policy on a local emulator: blue = declared, click
+          Deploy, watch it turn green. \`behold demo k8s\` stands a workload
+          up on a throwaway k3d cluster instead. Needs Docker (and per-demo
+          tools --list names). Loaded demos land in the panel's recents, so
+          switching between them is the Scope tab.
 
   export  Capture the live estate into a self-contained, interactive STATIC
           bundle (default ./behold-export) \u2014 every env/tier \xD7 zoom \xD7 radial,
@@ -5020,7 +5062,7 @@ ${USAGE}`);
   });
 }
 function warnIfNotChantProject(dir) {
-  if (existsSync10(join12(dir, "chant.config.ts"))) return;
+  if (existsSync10(join13(dir, "chant.config.ts"))) return;
   process.stderr.write(
     `behold: warning \u2014 ${dir} has no chant.config.ts; this doesn't look like a chant project.
         No project yet? \`behold demo\` serves a bundled working example (needs Docker).
@@ -5028,14 +5070,37 @@ function warnIfNotChantProject(dir) {
   );
 }
 async function runDemo(rest) {
+  const pkgRoot = join13(dirname5(fileURLToPath3(import.meta.url)), "..");
+  const registry = loadDemoRegistry(pkgRoot);
   let port = 4600;
+  let name;
   let dirArg;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--port") port = Number(rest[++i]);
-    else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
-    else if (!a.startsWith("-")) dirArg = a;
-    else {
+    else if (a === "--list") {
+      if (!registry.length) {
+        process.stdout.write("behold demo: no catalog in this install (demos.json missing)\n");
+        return;
+      }
+      for (const e of registry) {
+        const missing2 = missingRequirements(e);
+        const ready = missing2.length ? `needs ${missing2.join(", ")}` : "ready";
+        process.stdout.write(`  ${e.name.padEnd(14)} ${ready.padEnd(20)} ${e.description}
+`);
+      }
+      process.stdout.write("\nRun one: behold demo <name>   (bare `behold demo` = writes)\n");
+      return;
+    } else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
+    else if (!a.startsWith("-")) {
+      if (!name && registry.some((e) => e.name === a)) name = a;
+      else if (!dirArg) dirArg = a;
+      else {
+        process.stderr.write(`behold demo: unexpected argument '${a}'
+`);
+        process.exit(2);
+      }
+    } else {
       process.stderr.write(`behold demo: unexpected argument '${a}'
 `);
       process.exit(2);
@@ -5045,34 +5110,76 @@ async function runDemo(rest) {
     process.stderr.write("behold demo: --port must be a number\n");
     process.exit(2);
   }
-  const bundled = join12(dirname5(fileURLToPath3(import.meta.url)), "..", "example-writes");
-  if (!existsSync10(bundled)) {
-    process.stderr.write("behold demo: this install has no bundled example project (example-writes)\n");
+  const entry = registry.find((e) => e.name === (name ?? "writes"));
+  if (!entry) {
+    process.stderr.write(`behold demo: no "${name ?? "writes"}" in this install's catalog \u2014 behold demo --list
+`);
+    process.exit(2);
+  }
+  const missing = missingRequirements(entry);
+  if (missing.length) {
+    process.stderr.write(`behold demo ${entry.name}: missing ${missing.join(", ")} \u2014 install and re-run.
+`);
     process.exit(2);
   }
-  const target = resolve3(dirArg ?? "behold-demo");
+  const target = resolve3(
+    dirArg ?? (entry.name === "writes" && existsSync10("behold-demo") ? "behold-demo" : join13("behold-demos", entry.name))
+  );
   if (!existsSync10(target)) {
-    process.stdout.write(`behold demo \u2192 copying the example project to ${target} (it's yours \u2014 edit it)
+    if (entry.source === "bundled") {
+      const bundled = join13(pkgRoot, entry.dir);
+      if (!existsSync10(bundled)) {
+        process.stderr.write(`behold demo ${entry.name}: this install has no bundled ${entry.dir}
 `);
-    cpSync(bundled, target, {
-      recursive: true,
-      filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
-    });
+        process.exit(2);
+      }
+      process.stdout.write(`behold demo ${entry.name} \u2192 copying to ${target} (it's yours \u2014 edit it)
+`);
+      cpSync(bundled, target, {
+        recursive: true,
+        filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
+      });
+    } else {
+      process.stdout.write(`behold demo ${entry.name} \u2192 cloning ${entry.repo} to ${target}
+`);
+      const r = spawnSync2("git", ["clone", "--depth", "1", entry.repo, target], { stdio: "inherit" });
+      if (r.status !== 0) {
+        process.stderr.write(`behold demo ${entry.name}: clone failed
+`);
+        process.exit(r.status ?? 1);
+      }
+    }
   } else {
-    process.stdout.write(`behold demo \u2192 reusing ${target}
+    process.stdout.write(`behold demo ${entry.name} \u2192 reusing ${target}
 `);
   }
-  if (!existsSync10(join12(target, "node_modules"))) {
-    process.stdout.write("behold demo \u2192 npm install (the example's own chant + lexicons)\u2026\n");
-    const r = spawnSync("npm", ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
+  if (existsSync10(join13(target, "package.json")) && !existsSync10(join13(target, "node_modules"))) {
+    process.stdout.write(`behold demo ${entry.name} \u2192 npm install\u2026
+`);
+    const r = spawnSync2("npm", ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
     if (r.status !== 0) {
       process.stderr.write(`behold demo: npm install failed in ${target}${r.error ? ` (${r.error.message})` : ""}
 `);
       process.exit(r.status ?? 1);
     }
   }
-  process.stdout.write("behold demo \u2192 serving with a local emulator (Docker). Blue = declared; Deploy turns it green.\n");
-  await run3(["serve", target, "--local", "--env", "prod", "--port", String(port)]);
+  if (entry.setup) {
+    process.stdout.write(`behold demo ${entry.name} \u2192 ${entry.setup}
+`);
+    const r = spawnSync2(entry.setup, { cwd: target, stdio: "inherit", shell: true });
+    if (r.status !== 0) {
+      process.stderr.write(`behold demo ${entry.name}: setup failed (${entry.setup})
+`);
+      process.exit(r.status ?? 1);
+    }
+  }
+  process.stdout.write(`behold demo ${entry.name} \u2192 serving. Blue = declared; Deploy turns it green.
+`);
+  const serveDirs = entry.serve.dirs?.length ? entry.serve.dirs.map((d) => join13(target, d)) : [target];
+  const serveArgs = ["serve", ...serveDirs, "--port", String(port)];
+  if (entry.serve.local) serveArgs.push("--local");
+  if (entry.serve.env) serveArgs.push("--env", entry.serve.env);
+  await run3(serveArgs);
 }
 function injectEmulatorEnv(env) {
   process.env.LOOM_ENV ??= env ?? "local";

package/example-flux-estate/README.md

@@ -0,0 +1,41 @@
+# flux-estate — behold's GitOps estate demo (#211)
+
+Three chant projects served as one composed estate:
+
+- **control-plane/** — the Flux machinery: a `GitRepository` pointing at
+  behold's own public repo and one `Kustomization` per app. The reconcilers
+  deploy the apps; this project never applies a workload itself.
+- **app-a/** — a small web workload with explicit `metadata.namespace` on
+  every object: the fully-resolved half.
+- **app-b/** — the same workload with **no** namespace anywhere: the control
+  plane's `targetNamespace` stamps it at apply time. Idiomatic Flux, and the
+  deliberate exhibit of behold's namespace-mismatch note (behold#192) — a
+  plain live read scopes to `default`, finds nothing, and behold explains the
+  all-pending paint instead of letting it read as "not deployed".
+
+```sh
+npx @intentius/behold demo flux-estate
+```
+
+That stands up a throwaway k3d cluster (`behold-flux-demo`), installs Flux's
+controllers straight from the pinned release manifest (no `flux` CLI needed),
+applies the control plane, waits for the reconcilers to deploy both apps from
+this repo, and serves the three projects composed. What to look at:
+
+- The **estate**: per-project boundary boxes, and the `sourceRef` edges wiring
+  Kustomization → GitRepository across stacks.
+- The **overlay** (env `local`): app-a green, the control plane's CRs green,
+  app-b pending **with the note explaining why**.
+- The **runtime tier** on the control plane alone
+  (`behold serve control-plane --env local`, zoom: runtime): the workloads
+  Flux deployed, attributed back to the declaring Kustomization via its
+  labels (chant#1549).
+
+The app `manifests/` are committed `chant build` output — Flux syncs them
+from GitHub `main`, so changes to an app's source need a rebuild
+(`npm run build` in the app) and a merge before the cluster follows. To
+verify an unmerged branch: `BEHOLD_FLUX_REF=<branch> bash scripts/estate-up.sh`
+patches the live `GitRepository` (the declared source stays `main`).
+
+`bash scripts/estate-down.sh` deletes the cluster and restores your previous
+kubectl context.

package/example-flux-estate/app-a/chant.config.ts

@@ -0,0 +1,18 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// App project A. Deployed by the control plane's Flux Kustomization, never by
+// this project — its committed manifests/ (chant build output) are what Flux
+// syncs from the repo. behold serves it as part of the estate; the live
+// overlay reads the cluster through the same binding as every other member.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "app-a", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-flux-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-flux-estate/app-a/manifests/app.yaml

@@ -0,0 +1,56 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-a
+  namespace: app-a
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-a
+    chant.intentius.io/env: local
+    app: app-a
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: app-a
+  template:
+    metadata:
+      labels:
+        app: app-a
+    spec:
+      containers:
+        - name: web
+          image: nginxinc/nginx-unprivileged:1.27-alpine
+          ports:
+            - containerPort: 8080
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: '25m'
+              memory: '32Mi'
+            limits:
+              cpu: '100m'
+              memory: '64Mi'
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app-a
+  namespace: app-a
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-a
+    chant.intentius.io/env: local
+spec:
+  selector:
+    app: app-a
+  ports:
+    - port: 80
+      targetPort: 8080

package/example-flux-estate/app-a/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-flux-app-a",
+  "private": true,
+  "type": "module",
+  "description": "App project A: declares its workload WITH explicit namespaces — the fully-resolved half of the estate.",
+  "scripts": {
+    "build": "chant build src -o manifests/app.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.41.20",
+    "@intentius/chant-lexicon-k8s": "^0.41.20"
+  }
+}

package/example-flux-estate/app-a/src/app.ts

@@ -0,0 +1,35 @@
+// App A: one small web workload, namespace declared EXPLICITLY on every
+// object. Contrast app-b, which leaves namespace to the control plane's
+// targetNamespace — the two apps together show both halves of the Flux
+// namespace story (behold#192).
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+const labels = { app: "app-a" };
+const image = "nginxinc/nginx-unprivileged:1.27-alpine";
+
+export const deployment = new Deployment({
+  metadata: { name: "app-a", namespace: "app-a", labels },
+  spec: {
+    replicas: 1,
+    selector: { matchLabels: labels },
+    template: {
+      metadata: { labels },
+      spec: {
+        containers: [
+          {
+            name: "web",
+            image,
+            ports: [{ containerPort: 8080 }],
+            securityContext: { runAsNonRoot: true, runAsUser: 101, allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+            resources: { requests: { cpu: "25m", memory: "32Mi" }, limits: { cpu: "100m", memory: "64Mi" } },
+          },
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "app-a", namespace: "app-a" },
+  spec: { selector: labels, ports: [{ port: 80, targetPort: 8080 }] },
+});

package/example-flux-estate/app-a/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }

package/example-flux-estate/app-b/chant.config.ts

@@ -0,0 +1,20 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// App project B — the targetNamespace half of the estate: its objects declare
+// no metadata.namespace (see src/app.ts), so the control plane's
+// Kustomization stamps `app-b` at apply time. That is idiomatic Flux, AND it
+// means a plain live read scopes to `default` and finds nothing — behold's
+// namespace-mismatch note (behold#192) names exactly this, on purpose, in
+// this demo.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "app-b", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-flux-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-flux-estate/app-b/manifests/app.yaml

@@ -0,0 +1,54 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-b
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-b
+    chant.intentius.io/env: local
+    app: app-b
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: app-b
+  template:
+    metadata:
+      labels:
+        app: app-b
+    spec:
+      containers:
+        - name: web
+          image: nginxinc/nginx-unprivileged:1.27-alpine
+          ports:
+            - containerPort: 8080
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: '25m'
+              memory: '32Mi'
+            limits:
+              cpu: '100m'
+              memory: '64Mi'
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app-b
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: app-b
+    chant.intentius.io/env: local
+spec:
+  selector:
+    app: app-b
+  ports:
+    - port: 80
+      targetPort: 8080

package/example-flux-estate/app-b/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-flux-app-b",
+  "private": true,
+  "type": "module",
+  "description": "App project B: declares NO metadata.namespace — Flux's targetNamespace stamps it at apply time (the behold#192 shape).",
+  "scripts": {
+    "build": "chant build src -o manifests/app.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.41.20",
+    "@intentius/chant-lexicon-k8s": "^0.41.20"
+  }
+}

package/example-flux-estate/app-b/src/app.ts

@@ -0,0 +1,37 @@
+// App B: same small workload as app-a, with NO metadata.namespace anywhere —
+// the control plane's Kustomization stamps targetNamespace: app-b at apply
+// time. Idiomatic Flux (that's what the field is for), and the deliberate
+// exhibit of behold's namespace-mismatch note (behold#192): a plain live read
+// scopes to `default`, finds nothing, and behold explains the all-pending
+// paint instead of letting it read as "not deployed".
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+const labels = { app: "app-b" };
+const image = "nginxinc/nginx-unprivileged:1.27-alpine";
+
+export const deployment = new Deployment({
+  metadata: { name: "app-b", labels },
+  spec: {
+    replicas: 1,
+    selector: { matchLabels: labels },
+    template: {
+      metadata: { labels },
+      spec: {
+        containers: [
+          {
+            name: "web",
+            image,
+            ports: [{ containerPort: 8080 }],
+            securityContext: { runAsNonRoot: true, runAsUser: 101, allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+            resources: { requests: { cpu: "25m", memory: "32Mi" }, limits: { cpu: "100m", memory: "64Mi" } },
+          },
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "app-b" },
+  spec: { selector: labels, ports: [{ port: 80, targetPort: 8080 }] },
+});

package/example-flux-estate/app-b/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }