@checkstack/gitops-frontend 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @checkstack/gitops-frontend
 
+## 0.3.0
+
+### Minor Changes
+
+- 8ef367a: Added `registerSpecSchemaDocumentation` to EntityKindRegistry to allow plugins to provide detailed JSON Schemas for specific configurations. The frontend now displays these registered schemas as dropdown alternatives, improving the developer experience when authoring GitOps configurations.
+- cb65e9d: ### Schema-driven secret resolution, rotation invalidation, and security hardening
+
+  **Breaking**: Replaced `{ secretRef: "..." }` object syntax with `${{ secrets.NAME }}` template interpolation. The `secretField()`, `secretRefSchema`, `isSecretRef`, `SecretRef`, and `ResolvedSecretField` exports have been removed from `@checkstack/gitops-common`.
+
+  **Breaking**: `ReconcileContext.resolveSecretsBySchema()` now returns `{ resolved: T; warnings: string[] }` instead of `T` directly. Plugins must destructure the result. Warnings contain messages for `${{ secrets.NAME }}` templates found in non-secret fields (fields without `x-secret` annotation).
+
+  **New features**:
+
+  - Secrets can be referenced in **any string field** using `${{ secrets.NAME }}` syntax
+  - Inline interpolation is supported: `"postgres://user:${{ secrets.DB_PASS }}@host/db"`
+  - Resolution is **schema-driven** — reuses the existing `configString({ "x-secret": true })` pattern from DynamicForm
+  - Secret rotation now automatically invalidates affected entities, triggering re-reconciliation on the next sync cycle
+  - New `getSecretUsage` RPC endpoint to look up which entities reference a given secret
+  - Secrets UI now shows an expandable usage panel per secret showing referencing entities
+  - Reconciliation warnings: templates in non-secret fields are detected and surfaced in the provenance UI
+  - New `secretNameSchema` and `SECRET_NAME_REGEX` exports for validating secret names
+
+  **Security**:
+
+  - Secret names are validated at creation: must start with a letter, contain only `[a-zA-Z0-9_-]`, max 63 chars
+  - Secrets are validated to exist at sync time but **not pre-resolved** into the spec
+  - Templates in `metadata` fields are **rejected** to prevent secret leaks via display fields
+  - Only fields with `x-secret` schema annotations get resolved — no escape hatch
+  - Templates in non-secret fields emit warnings (stored in provenance, visible in UI) instead of silently passing
+
+  **Migration**: Update YAML descriptors to use `${{ secrets.NAME }}` instead of `secretRef: name`. Remove `secretField()` imports from plugin schemas — use `configString({ "x-secret": true })` to annotate secret fields. Destructure `const { resolved } = await context.resolveSecretsBySchema({ value, schema })` (return type changed from `T` to `{ resolved: T; warnings: string[] }`).
+
+### Patch Changes
+
+- Updated dependencies [8ef367a]
+- Updated dependencies [cb65e9d]
+  - @checkstack/gitops-common@0.2.0
+
+## 0.2.1
+
+### Patch Changes
+
+- 86bab6a: ### GitOps: Fix authentication token handling
+
+  - Made `authToken` optional in `ReconcileProviderParams` and `ScraperOptions` to support unauthenticated access to public repositories
+  - GitHub and GitLab scrapers now conditionally set authentication headers only when a token is provided
+  - Sync worker now decrypts the encrypted `authToken` from the database before passing it to scrapers, fixing authentication failures caused by sending encrypted values in HTTP headers
+
+  ### SLO: Fix premature Nines Club achievement unlock
+
+  - The "Nines Club" achievement now requires both ≥99.99% availability **and** a 365-day compliance streak, preventing immediate unlock on newly created SLOs with 100% default availability
+
+  ### SLO: Align frontend achievement descriptions with backend criteria
+
+  - Fixed mismatched descriptions for Iron Uptime (7-day, not 30), Diamond Uptime (30-day, not 90), Clean Sheet (rolling window, not quarter), Full Coverage (3+ SLOs, not all systems in group), and Nines Club (99.99%)
+
+  ### SLO: Enrich milestones with system names
+
+  - The `getRecentMilestones` endpoint now resolves human-readable system names via the Catalog API instead of returning raw system IDs
+
+- Updated dependencies [86bab6a]
+  - @checkstack/gitops-common@0.1.1
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/gitops-frontend",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.tsx",
   "checkstack": {
@@ -14,8 +14,8 @@
   "dependencies": {
     "@checkstack/common": "0.6.5",
     "@checkstack/frontend-api": "0.3.9",
-    "@checkstack/gitops-common": "0.0.1",
-    "@checkstack/ui": "1.3.5",
+    "@checkstack/gitops-common": "0.1.1",
+    "@checkstack/ui": "1.3.6",
     "lucide-react": "^0.344.0",
     "react": "^18.2.0",
     "react-router-dom": "^6.22.0"

package/src/components/ProvenanceStatus.tsx

@@ -61,6 +61,9 @@ export const ProvenanceStatus = () => {
   const synced = entries.filter((e) => e.status === "synced");
   const errors = entries.filter((e) => e.status === "error");
   const orphaned = entries.filter((e) => e.status === "orphaned");
+  const withWarnings = entries.filter(
+    (e) => e.warnings.length > 0 && e.status === "synced",
+  );
 
   const statusIcon = (status: Provenance["status"]) => {
     switch (status) {
@@ -107,6 +110,19 @@ export const ProvenanceStatus = () => {
                   {entry.errorMessage}
                 </div>
               )}
+              {entry.warnings.length > 0 && (
+                <div className="mt-1 space-y-0.5">
+                  {entry.warnings.map((warning, index) => (
+                    <div
+                      key={index}
+                      className="text-xs text-amber-500 flex items-start gap-1"
+                    >
+                      <AlertTriangle className="w-3 h-3 shrink-0 mt-0.5" />
+                      <span className="truncate">{warning}</span>
+                    </div>
+                  ))}
+                </div>
+              )}
             </div>
           </div>
 
@@ -148,7 +164,7 @@ export const ProvenanceStatus = () => {
     <>
       <div className="space-y-6">
         {/* Summary */}
-        <div className="grid grid-cols-3 gap-4">
+        <div className="grid grid-cols-4 gap-4">
           <Card>
             <CardContent className="pt-6">
               <div className="flex items-center gap-2">
@@ -176,6 +192,15 @@ export const ProvenanceStatus = () => {
               </div>
             </CardContent>
           </Card>
+          <Card>
+            <CardContent className="pt-6">
+              <div className="flex items-center gap-2">
+                <AlertTriangle className="w-5 h-5 text-amber-500" />
+                <span className="text-2xl font-bold">{withWarnings.length}</span>
+                <span className="text-sm text-muted-foreground">Warnings</span>
+              </div>
+            </CardContent>
+          </Card>
         </div>
 
         {/* Orphaned entities — shown first if any */}
@@ -196,6 +221,22 @@ export const ProvenanceStatus = () => {
           </Card>
         )}
 
+        {/* Warnings */}
+        {withWarnings.length > 0 && (
+          <Card>
+            <CardHeader>
+              <CardTitle className="flex items-center gap-2">
+                <AlertTriangle className="w-5 h-5 text-amber-500" />
+                Sync Warnings
+              </CardTitle>
+              <p className="text-xs text-muted-foreground mt-1">
+                These entities contain secret templates in non-secret fields. The templates will not be resolved.
+              </p>
+            </CardHeader>
+            <CardContent>{renderEntryList(withWarnings, false)}</CardContent>
+          </Card>
+        )}
+
         {/* Errors */}
         {errors.length > 0 && (
           <Card>

package/src/components/ProviderEditor.tsx

@@ -24,7 +24,7 @@ interface ProviderEditorProps {
     target: string;
     pathPattern: string;
     baseUrl?: string;
-    authToken?: string;
+    authToken?: string | null;
     syncInterval?: number;
     deletionPolicy?: "orphan" | "auto";
   }) => void;
@@ -50,6 +50,7 @@ export const ProviderEditor: React.FC<ProviderEditorProps> = ({
   const [pathPattern, setPathPattern] = useState(initialData?.pathPattern ?? ".checkstack/**/*.yaml");
   const [baseUrl, setBaseUrl] = useState(initialData?.baseUrl ?? "");
   const [authToken, setAuthToken] = useState("");
+  const [clearToken, setClearToken] = useState(false);
   const [syncInterval, setSyncInterval] = useState(String(initialData?.syncInterval ?? 300));
   const [deletionPolicy, setDeletionPolicy] = useState<"orphan" | "auto">(
     initialData?.deletionPolicy ?? "orphan",
@@ -62,6 +63,7 @@ export const ProviderEditor: React.FC<ProviderEditorProps> = ({
       setPathPattern(initialData?.pathPattern ?? ".checkstack/**/*.yaml");
       setBaseUrl(initialData?.baseUrl ?? "");
       setAuthToken("");
+      setClearToken(false);
       setSyncInterval(String(initialData?.syncInterval ?? 300));
       setDeletionPolicy(initialData?.deletionPolicy ?? "orphan");
     }
@@ -71,12 +73,24 @@ export const ProviderEditor: React.FC<ProviderEditorProps> = ({
     e.preventDefault();
     if (!target.trim() || !pathPattern.trim()) return;
 
+    // Determine authToken value:
+    // - clearToken=true → null (explicitly remove)
+    // - non-empty string → new token
+    // - empty string → undefined (keep current)
+    let authTokenValue: string | null | undefined;
+    if (clearToken) {
+      // eslint-disable-next-line unicorn/no-null
+      authTokenValue = null;
+    } else if (authToken.trim()) {
+      authTokenValue = authToken.trim();
+    }
+
     onSave({
       type,
       target: target.trim(),
       pathPattern: pathPattern.trim(),
       baseUrl: baseUrl.trim() || undefined,
-      authToken: authToken.trim() || undefined,
+      authToken: authTokenValue,
       syncInterval: Number(syncInterval) || 300,
       deletionPolicy,
     });
@@ -160,13 +174,45 @@ export const ProviderEditor: React.FC<ProviderEditorProps> = ({
               <Label htmlFor="provider-auth-token">
                 Auth Token {initialData ? "(leave empty to keep current)" : "(optional)"}
               </Label>
-              <Input
-                id="provider-auth-token"
-                type="password"
-                placeholder="ghp_xxxx..."
-                value={authToken}
-                onChange={(e) => setAuthToken(e.target.value)}
-              />
+              {clearToken ? (
+                <div className="flex items-center gap-2 p-2 rounded-md border border-border bg-muted/50">
+                  <span className="text-sm text-muted-foreground flex-1">
+                    Token will be removed on save
+                  </span>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    onClick={() => setClearToken(false)}
+                  >
+                    Undo
+                  </Button>
+                </div>
+              ) : (
+                <div className="flex gap-2">
+                  <Input
+                    id="provider-auth-token"
+                    type="password"
+                    placeholder="ghp_xxxx..."
+                    value={authToken}
+                    onChange={(e) => setAuthToken(e.target.value)}
+                    className="flex-1"
+                  />
+                  {initialData && (
+                    <Button
+                      type="button"
+                      variant="outline"
+                      size="sm"
+                      onClick={() => {
+                        setAuthToken("");
+                        setClearToken(true);
+                      }}
+                    >
+                      Remove
+                    </Button>
+                  )}
+                </div>
+              )}
             </div>
 
             <div className="grid grid-cols-2 gap-4">

package/src/components/ProviderList.tsx

@@ -119,7 +119,7 @@ export const ProviderList = () => {
     target: string;
     pathPattern: string;
     baseUrl?: string;
-    authToken?: string;
+    authToken?: string | null;
     syncInterval?: number;
     deletionPolicy?: "orphan" | "auto";
   }) => {
@@ -136,7 +136,11 @@ export const ProviderList = () => {
         },
       });
     } else {
-      createMutation.mutate(data);
+      // On create, authToken is always string|undefined (Remove button not shown)
+      createMutation.mutate({
+        ...data,
+        authToken: data.authToken ?? undefined,
+      });
     }
   };
 

package/src/components/SecretEditor.tsx

@@ -10,6 +10,7 @@ import {
   DialogTitle,
   DialogFooter,
 } from "@checkstack/ui";
+import { SECRET_NAME_REGEX } from "@checkstack/gitops-common";
 
 interface SecretEditorProps {
   open: boolean;
@@ -34,9 +35,18 @@ export const SecretEditor: React.FC<SecretEditorProps> = ({
     }
   }, [open]);
 
+  const nameError =
+    name.length > 0 && !SECRET_NAME_REGEX.test(name)
+      ? "Must start with a letter and contain only letters, digits, underscores, or hyphens"
+      : name.length > 63
+        ? "Must be 63 characters or fewer"
+        : undefined;
+
+  const canSubmit = name.trim().length > 0 && !nameError && value.trim().length > 0;
+
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
-    if (!name.trim() || !value.trim()) return;
+    if (!canSubmit) return;
 
     onSave({
       name: name.trim(),
@@ -64,12 +74,16 @@ export const SecretEditor: React.FC<SecretEditorProps> = ({
                 placeholder="e.g. GITHUB_TOKEN"
                 value={name}
                 onChange={(e) => setName(e.target.value)}
-                className="font-mono"
+                className={`font-mono ${nameError ? "border-destructive" : ""}`}
                 required
               />
-              <p className="text-xs text-muted-foreground">
-                Referenced as <code className="text-xs">{"${{ secrets.NAME }}"}</code> in descriptors.
-              </p>
+              {nameError ? (
+                <p className="text-xs text-destructive">{nameError}</p>
+              ) : (
+                <p className="text-xs text-muted-foreground">
+                  Referenced as <code className="text-xs">{"${{ secrets.NAME }}"}</code> in descriptors.
+                </p>
+              )}
             </div>
 
             <div className="space-y-2">
@@ -99,7 +113,7 @@ export const SecretEditor: React.FC<SecretEditorProps> = ({
             <Button type="button" variant="outline" onClick={onClose}>
               Cancel
             </Button>
-            <Button type="submit" disabled={!name.trim() || !value.trim()}>
+            <Button type="submit" disabled={!canSubmit}>
               Create Secret
             </Button>
           </DialogFooter>
@@ -108,3 +122,4 @@ export const SecretEditor: React.FC<SecretEditorProps> = ({
     </Dialog>
   );
 };
+

package/src/components/SecretList.tsx

@@ -15,14 +15,56 @@ import {
   EmptyState,
   ConfirmationModal,
   useToast,
+  Badge,
 } from "@checkstack/ui";
-import { Plus, RotateCw, Trash2, KeyRound } from "lucide-react";
+import { Plus, RotateCw, Trash2, KeyRound, ChevronDown, ChevronRight } from "lucide-react";
 import { extractErrorMessage } from "@checkstack/common";
 import { SecretEditor } from "./SecretEditor";
 import { SecretRotateDialog } from "./SecretRotateDialog";
 
 const formatDate = (date: Date) => new Date(date).toLocaleString();
 
+/** Expandable usage panel for a single secret. */
+const SecretUsagePanel = ({ secretName }: { secretName: string }) => {
+  const client = usePluginClient(GitOpsApi);
+  const { data: usage, isLoading } = client.getSecretUsage.useQuery({
+    secretName,
+  });
+
+  if (isLoading) {
+    return (
+      <div className="text-xs text-muted-foreground py-2 px-4">Loading…</div>
+    );
+  }
+
+  if (!usage || usage.length === 0) {
+    return (
+      <div className="text-xs text-muted-foreground py-2 px-4">
+        Not referenced by any entities.
+      </div>
+    );
+  }
+
+  return (
+    <div className="px-4 pb-3 space-y-1">
+      {usage.map((entry) => (
+        <div
+          key={`${entry.kind}::${entry.entityName}`}
+          className="flex items-center gap-2 text-xs text-muted-foreground"
+        >
+          <Badge variant="outline" className="text-[10px] font-mono px-1.5 py-0">
+            {entry.kind}
+          </Badge>
+          <span className="font-medium text-foreground">{entry.entityName}</span>
+          <span className="hidden sm:inline truncate">
+            {entry.repository}/{entry.filePath}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+};
+
 export const SecretList = () => {
   const client = usePluginClient(GitOpsApi);
   const accessApi = useApi(accessApiRef);
@@ -42,6 +84,9 @@ export const SecretList = () => {
     secretId: string;
     secretName: string;
   }>({ isOpen: false, secretId: "", secretName: "" });
+  const [expandedSecrets, setExpandedSecrets] = useState<Set<string>>(
+    new Set(),
+  );
 
   const { data: secrets, isLoading, refetch } = client.listSecrets.useQuery({});
 
@@ -78,6 +123,18 @@ export const SecretList = () => {
     },
   });
 
+  const toggleExpanded = (secretId: string) => {
+    setExpandedSecrets((prev) => {
+      const next = new Set(prev);
+      if (next.has(secretId)) {
+        next.delete(secretId);
+      } else {
+        next.add(secretId);
+      }
+      return next;
+    });
+  };
+
   return (
     <>
       <Card>
@@ -108,64 +165,83 @@ export const SecretList = () => {
             />
           ) : (
             <div className="space-y-3">
-              {secrets.map((secret) => (
-                <div
-                  key={secret.id}
-                  className="flex items-center justify-between p-4 rounded-lg border border-border bg-background/50 hover:bg-background/80 transition-colors"
-                >
-                  <div className="flex items-center gap-3 min-w-0">
-                    <KeyRound className="w-4 h-4 text-muted-foreground shrink-0" />
-                    <div className="min-w-0">
-                      <div className="font-medium font-mono text-sm">
-                        {secret.name}
-                      </div>
-                      {secret.description && (
-                        <div className="text-xs text-muted-foreground mt-0.5 truncate">
-                          {secret.description}
+              {secrets.map((secret) => {
+                const isExpanded = expandedSecrets.has(secret.id);
+                return (
+                  <div
+                    key={secret.id}
+                    className="rounded-lg border border-border bg-background/50 hover:bg-background/80 transition-colors"
+                  >
+                    <div className="flex items-center justify-between p-4">
+                      <button
+                        type="button"
+                        className="flex items-center gap-3 min-w-0 cursor-pointer bg-transparent border-none p-0 text-left"
+                        onClick={() => toggleExpanded(secret.id)}
+                        title={isExpanded ? "Hide usage" : "Show usage"}
+                      >
+                        {isExpanded ? (
+                          <ChevronDown className="w-3.5 h-3.5 text-muted-foreground shrink-0" />
+                        ) : (
+                          <ChevronRight className="w-3.5 h-3.5 text-muted-foreground shrink-0" />
+                        )}
+                        <KeyRound className="w-4 h-4 text-muted-foreground shrink-0" />
+                        <div className="min-w-0">
+                          <div className="font-medium font-mono text-sm">
+                            {secret.name}
+                          </div>
+                          {secret.description && (
+                            <div className="text-xs text-muted-foreground mt-0.5 truncate">
+                              {secret.description}
+                            </div>
+                          )}
                         </div>
-                      )}
-                    </div>
-                  </div>
+                      </button>
 
-                  <div className="flex items-center gap-4 shrink-0">
-                    <div className="text-right text-xs text-muted-foreground hidden md:block">
-                      <div>Updated: {formatDate(secret.updatedAt)}</div>
-                    </div>
+                      <div className="flex items-center gap-4 shrink-0">
+                        <div className="text-right text-xs text-muted-foreground hidden md:block">
+                          <div>Updated: {formatDate(secret.updatedAt)}</div>
+                        </div>
 
-                    {canManage && (
-                      <div className="flex items-center gap-1">
-                        <Button
-                          variant="ghost"
-                          size="icon"
-                          onClick={() =>
-                            setRotatingSecret({
-                              id: secret.id,
-                              name: secret.name,
-                            })
-                          }
-                          title="Rotate secret"
-                        >
-                          <RotateCw className="w-4 h-4" />
-                        </Button>
-                        <Button
-                          variant="ghost"
-                          size="icon"
-                          onClick={() =>
-                            setConfirmModal({
-                              isOpen: true,
-                              secretId: secret.id,
-                              secretName: secret.name,
-                            })
-                          }
-                          title="Delete secret"
-                        >
-                          <Trash2 className="w-4 h-4" />
-                        </Button>
+                        {canManage && (
+                          <div className="flex items-center gap-1">
+                            <Button
+                              variant="ghost"
+                              size="icon"
+                              onClick={() =>
+                                setRotatingSecret({
+                                  id: secret.id,
+                                  name: secret.name,
+                                })
+                              }
+                              title="Rotate secret"
+                            >
+                              <RotateCw className="w-4 h-4" />
+                            </Button>
+                            <Button
+                              variant="ghost"
+                              size="icon"
+                              onClick={() =>
+                                setConfirmModal({
+                                  isOpen: true,
+                                  secretId: secret.id,
+                                  secretName: secret.name,
+                                })
+                              }
+                              title="Delete secret"
+                            >
+                              <Trash2 className="w-4 h-4" />
+                            </Button>
+                          </div>
+                        )}
                       </div>
+                    </div>
+
+                    {isExpanded && (
+                      <SecretUsagePanel secretName={secret.name} />
                     )}
                   </div>
-                </div>
-              ))}
+                );
+              })}
             </div>
           )}
         </CardContent>

package/src/pages/KindRegistryPage.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useState, useCallback, useMemo, useEffect } from "react";
 import {
   Card,
   CardContent,
@@ -7,8 +7,22 @@ import {
   CardTitle,
   Badge,
   PageLayout,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  CodeEditor,
+  Markdown,
+  MarkdownBlock,
 } from "@checkstack/ui";
-import { ChevronDown, ChevronRight, Puzzle, Blocks } from "lucide-react";
+import {
+  ChevronDown,
+  ChevronRight,
+  Puzzle,
+  Blocks,
+  BookOpen,
+} from "lucide-react";
 import { usePluginClient } from "@checkstack/frontend-api";
 import { GitOpsApi } from "@checkstack/gitops-common";
 import { extractErrorMessage } from "@checkstack/common";
@@ -29,11 +43,23 @@ interface JsonSchemaProperty {
 interface KindDescription {
   apiVersion: string;
   kind: string;
+  metadataSchema: JsonSchemaProperty;
   specSchema: JsonSchemaProperty;
   extensions: Array<{
     namespace: string;
     specSchema: JsonSchemaProperty;
   }>;
+  specSchemaDocumentation?: Array<{
+    fieldPath: string;
+    variantId?: string;
+    label: string;
+    description?: string;
+    specSchema: JsonSchemaProperty;
+    conditions?: Array<{
+      fieldPath: string;
+      variantIds: string[];
+    }>;
+  }>;
 }
 
 // ─── Schema Display ────────────────────────────────────────────────────────
@@ -87,8 +113,11 @@ function SchemaPropertyDisplay({
             )}
             : <SchemaPropertyDisplay schema={value} depth={depth + 1} />
             {value.description && (
-              <span className="text-muted-foreground ml-2 text-xs">
-                // {value.description}
+              <span className="text-muted-foreground ml-2 text-xs inline-flex items-center gap-1">
+                //{" "}
+                <Markdown size="sm" className="inline">
+                  {value.description}
+                </Markdown>
               </span>
             )}
           </div>
@@ -160,12 +189,31 @@ function SchemaBlock({
 // ─── YAML Example Generator ────────────────────────────────────────────────
 
 function generateYamlExample({ kind }: { kind: KindDescription }): string {
-  const lines = [
-    `apiVersion: ${kind.apiVersion}`,
-    `kind: ${kind.kind}`,
-    "metadata:",
-    `  name: my-${kind.kind.toLowerCase()}`,
-  ];
+  const lines = [`apiVersion: ${kind.apiVersion}`, `kind: ${kind.kind}`];
+
+  if (kind.metadataSchema) {
+    lines.push("metadata:");
+    const metadataProps = kind.metadataSchema.properties ?? {};
+    const metadataRequired = new Set(kind.metadataSchema.required);
+
+    for (const [key, prop] of Object.entries(metadataProps)) {
+      // Provide a nice default for name instead of generic "..."
+      const customProp =
+        key === "name"
+          ? { ...prop, default: `my-${kind.kind.toLowerCase()}` }
+          : prop;
+
+      emitProperty({
+        lines,
+        key,
+        prop: customProp,
+        indent: 2,
+        required: metadataRequired.has(key),
+      });
+    }
+  } else {
+    lines.push("metadata:", `  name: my-${kind.kind.toLowerCase()}`);
+  }
 
   const baseProps = kind.specSchema.properties ?? {};
   const hasBaseProps = Object.keys(baseProps).length > 0;
@@ -380,10 +428,149 @@ function scalarExample({ prop }: { prop: JsonSchemaProperty }): string {
   }
 }
 
+// ─── Spec Schema Documentation ─────────────────────────────────────────────
+
+function SpecSchemaDocumentationSection({
+  docs,
+}: {
+  docs: NonNullable<KindDescription["specSchemaDocumentation"]>;
+}) {
+  const [selections, setSelections] = useState<Record<string, string>>({});
+
+  const handleSelect = useCallback((fieldPath: string, variantId: string) => {
+    setSelections((prev) => {
+      if (prev[fieldPath] === variantId) return prev;
+      return { ...prev, [fieldPath]: variantId };
+    });
+  }, []);
+
+  const groupedDocs: Record<string, typeof docs> = {};
+  for (const doc of docs) {
+    if (!groupedDocs[doc.fieldPath]) {
+      groupedDocs[doc.fieldPath] = [];
+    }
+    groupedDocs[doc.fieldPath].push(doc);
+  }
+
+  return (
+    <div className="space-y-6">
+      <h4 className="text-sm font-medium text-muted-foreground flex items-center gap-2">
+        <BookOpen className="h-4 w-4" />
+        Additional Schemas
+      </h4>
+
+      {Object.entries(groupedDocs).map(([fieldPath, fieldDocs]) => {
+        return (
+          <SpecSchemaDocumentationField
+            key={fieldPath}
+            fieldPath={fieldPath}
+            docs={fieldDocs.toSorted((a, b) => a.label.localeCompare(b.label))}
+            selections={selections}
+            onSelect={handleSelect}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+function SpecSchemaDocumentationField({
+  fieldPath,
+  docs,
+  selections,
+  onSelect,
+}: {
+  fieldPath: string;
+  docs: NonNullable<KindDescription["specSchemaDocumentation"]>;
+  selections: Record<string, string>;
+  onSelect: (fieldPath: string, variantId: string) => void;
+}) {
+  const availableDocs = useMemo(() => {
+    return docs.filter((doc) => {
+      if (!doc.conditions || doc.conditions.length === 0) return true;
+      return doc.conditions.every((cond) => {
+        const selectedForField = selections[cond.fieldPath];
+        if (!selectedForField) return false;
+        return cond.variantIds.includes(selectedForField);
+      });
+    });
+  }, [docs, selections]);
+
+  const currentSelection = selections[fieldPath] || "";
+  const isValidSelection =
+    currentSelection !== "" &&
+    availableDocs.some((d) => (d.variantId || d.label) === currentSelection);
+
+  useEffect(() => {
+    if (currentSelection !== "" && !isValidSelection) {
+      onSelect(fieldPath, "");
+    }
+  }, [currentSelection, isValidSelection, onSelect, fieldPath]);
+
+  if (availableDocs.length === 0) {
+    return <></>;
+  }
+
+  const selectedDoc = availableDocs.find(
+    (d) => (d.variantId || d.label) === currentSelection,
+  );
+
+  return (
+    <div className="border rounded-lg p-4 space-y-4">
+      <div className="flex items-center justify-between gap-4 flex-wrap">
+        <div className="flex items-center gap-2">
+          <Badge variant="secondary" className="font-mono">
+            {fieldPath}
+          </Badge>
+          <span className="text-sm text-muted-foreground">
+            {availableDocs.length} variant{availableDocs.length > 1 ? "s" : ""}
+          </span>
+        </div>
+
+        <div className="w-full sm:w-64">
+          <Select
+            value={isValidSelection ? currentSelection : ""}
+            onValueChange={(val) => onSelect(fieldPath, val)}
+          >
+            <SelectTrigger>
+              <SelectValue placeholder="Select a schema variant..." />
+            </SelectTrigger>
+            <SelectContent>
+              {availableDocs.map((doc, i) => (
+                <SelectItem key={i} value={doc.variantId || doc.label}>
+                  {doc.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+      </div>
+
+      {selectedDoc ? (
+        <div className="space-y-3 animate-in fade-in slide-in-from-top-2 duration-200">
+          {selectedDoc.description && (
+            <div className="text-sm text-muted-foreground">
+              <MarkdownBlock>{selectedDoc.description}</MarkdownBlock>
+            </div>
+          )}
+          <div className="bg-muted rounded-md p-3 overflow-x-auto">
+            <SchemaPropertyDisplay schema={selectedDoc.specSchema} />
+          </div>
+        </div>
+      ) : (
+        <div className="text-sm text-muted-foreground italic bg-muted/50 rounded-md p-4 text-center">
+          Select a variant from the dropdown above to view its schema.
+        </div>
+      )}
+    </div>
+  );
+}
+
 // ─── Kind Card ─────────────────────────────────────────────────────────────
 
 function KindCard({ kind }: { kind: KindDescription }) {
   const [isOpen, setIsOpen] = useState(false);
+  const yamlExample = useMemo(() => generateYamlExample({ kind }), [kind]);
 
   return (
     <Card className="mb-3">
@@ -423,6 +610,12 @@ function KindCard({ kind }: { kind: KindDescription }) {
 
       {isOpen && (
         <CardContent className="pt-0 space-y-6">
+          {/* Entity Envelope Fields */}
+          <SchemaBlock
+            schema={kind.metadataSchema}
+            label="Entity Envelope Fields"
+          />
+
           {/* Base Spec Schema */}
           <SchemaBlock schema={kind.specSchema} label="Base Spec Schema" />
 
@@ -451,14 +644,28 @@ function KindCard({ kind }: { kind: KindDescription }) {
             </div>
           )}
 
+          {/* Spec Schema Documentation */}
+          {kind.specSchemaDocumentation &&
+            kind.specSchemaDocumentation.length > 0 && (
+              <SpecSchemaDocumentationSection
+                docs={kind.specSchemaDocumentation}
+              />
+            )}
+
           {/* YAML Example */}
           <div>
             <h4 className="text-sm font-medium mb-2 text-muted-foreground">
               YAML Example
             </h4>
-            <pre className="bg-muted rounded-md p-3 overflow-x-auto text-sm">
-              <code>{generateYamlExample({ kind })}</code>
-            </pre>
+            <div className="rounded-md overflow-hidden border border-input">
+              <CodeEditor
+                value={yamlExample}
+                language="yaml"
+                readOnly
+                onChange={() => {}}
+                minHeight={`${Math.max(100, yamlExample.split("\n").length * 20 + 20)}px`}
+              />
+            </div>
           </div>
         </CardContent>
       )}