fix(release): harden release tooling and fix doc link issues

Several correctness and safety issues addressed together:

- Hardcoded `localhost:3000` URLs in MDX files would 404 in production;
  converted to relative `/docs/main/` paths.
- `git tag --force` in the edge release script could silently overwrite
  an existing tag; switched to plain `git tag` and added an explicit
  same-day collision guard to fail fast instead.
- Changelog validator now rejects `internal-docs` references that point
  to `/docs/` paths other than `/docs/main/`, preventing changelog
  entries from linking to the wrong versioned docs.
- Check/Todo icon components were duplicated across every docs version
  directory, risking drift; extracted to `components/ui/` as shared
  `CheckCircleIcon` and `TodoIcon` components.
- Release script now resets `changelog/main/review.yaml` after tagging
  so the next release cycle starts clean.

Author: fullykubed

.claude/skills/changelog/scripts/validate-changelog.ts

@@ -14,7 +14,7 @@ const LOG_YAML_PATH = join(CHANGELOG_DIR, "main/log.yaml");
 const LOG_SCHEMA_PATH = join(CHANGELOG_DIR, "log.schema.json");
 
 interface Finding {
-  level: "WARN" | "INFO";
+  level: "ERROR" | "WARN" | "INFO";
   changeIndex: number;
   changeType: string;
   message: string;
@@ -129,6 +129,24 @@ function validateChange(change: Change, index: number): Finding[] {
     }
   }
 
+  // Check: internal-docs references that start with /docs/ MUST use /docs/main/
+  if (Array.isArray(change.references)) {
+    for (const ref of change.references) {
+      if (
+        ref.type === "internal-docs" &&
+        ref.link.startsWith("/docs/") &&
+        !ref.link.startsWith("/docs/main/")
+      ) {
+        findings.push({
+          level: "ERROR",
+          changeIndex: changeNumber,
+          changeType,
+          message: `${summaryLabel} has an internal-docs reference linking to "${ref.link}" — versioned docs references must point to /docs/main/`,
+        });
+      }
+    }
+  }
+
   // Check: all entries with impacts SHOULD have impact summaries
   if (Array.isArray(change.impacts)) {
     for (const impact of change.impacts) {
@@ -248,6 +266,7 @@ function main(): void {
     console.log(`[${finding.level}] ${location}: ${finding.message}`);
   }
 
+  const errorCount = allFindings.filter((f) => f.level === "ERROR").length;
   const warnCount = allFindings.filter((f) => f.level === "WARN").length;
   const infoCount = allFindings.filter((f) => f.level === "INFO").length;
 
@@ -256,11 +275,12 @@ function main(): void {
   }
 
   console.log("Summary:");
+  console.log(`  Errors: ${errorCount}`);
   console.log(`  Warnings: ${warnCount}`);
   console.log(`  Info: ${infoCount}`);
   console.log(`  Total changes checked: ${changes.length}`);
 
-  if (warnCount > 0) {
+  if (errorCount > 0 || warnCount > 0) {
     process.exit(1);
   }
 }

packages/nix/localDevShell/scripts/ds-validate-changelog.ts

@@ -91,6 +91,29 @@ function validateFile(
     }
   }
 
+  // Validate that internal-docs references point to /docs/main/
+  const changes = (logData["changes"] ?? []) as Array<{
+    references?: Array<{ type: string; link: string }>;
+  }>;
+  for (let i = 0; i < changes.length; i++) {
+    const refs = changes[i]?.references;
+    if (!Array.isArray(refs)) continue;
+    for (const ref of refs) {
+      if (
+        ref.type === "internal-docs" &&
+        ref.link.startsWith("/docs/") &&
+        !ref.link.startsWith("/docs/main/")
+      ) {
+        result.errors.push(
+          `Field "/changes/${i}/references": internal-docs reference links to "${ref.link}" but versioned docs references must point to /docs/main/`
+        );
+      }
+    }
+  }
+  if (result.errors.length > 0) {
+    return result;
+  }
+
   result.valid = true;
   return result;
 }

packages/nix/localDevShell/scripts/make-new-edge-release.sh

@@ -19,6 +19,21 @@ if [[ -n $(git status --porcelain) ]]; then
   exit 1
 fi
 
+# Get the new version tag and derive the edge directory name (strip "edge." prefix)
+VERSION_TAG="edge.$(date +'%y-%m-%d')"
+EDGE_DATE="${VERSION_TAG#edge.}"
+EDGE_ENTRY_DIR="$CHANGELOG_DIR/edge/$EDGE_DATE"
+
+# Guard against same-day release collision
+if git tag -l "$VERSION_TAG" | grep -q .; then
+  echo "Error: Tag $VERSION_TAG already exists. Only one edge release per day is supported."
+  exit 1
+fi
+if [ -d "$EDGE_ENTRY_DIR" ]; then
+  echo "Error: Changelog directory $EDGE_ENTRY_DIR already exists. Only one edge release per day is supported."
+  exit 1
+fi
+
 # Remove existing edge release
 rm -rf "$DOCS_DIR/edge"
 
@@ -31,11 +46,6 @@ find "$DOCS_DIR/edge" -type f -exec sed -i -E "s|([\"'(])/docs/main|\1/docs/edge
 # Search and replace __PANFACTUM_VERSION_MAIN__ with __PANFACTUM_VERSION_EDGE__ in all files
 find "$DOCS_DIR/edge" -type f -exec sed -i -E "s|__PANFACTUM_VERSION_MAIN__|__PANFACTUM_VERSION_EDGE__|g" {} \;
 
-# Get the new version tag and derive the edge directory name (strip "edge." prefix)
-VERSION_TAG="edge.$(date +'%y-%m-%d')"
-EDGE_DATE="${VERSION_TAG#edge.}"
-EDGE_ENTRY_DIR="$CHANGELOG_DIR/edge/$EDGE_DATE"
-
 # Update the version tag in constants
 jq --arg tag "$VERSION_TAG" '.versions.edge.ref = "\($tag)"' "$CONSTANTS_FILE" >"$CONSTANTS_FILE.tmp" && mv "$CONSTANTS_FILE.tmp" "$CONSTANTS_FILE"
 
@@ -54,10 +64,16 @@ summary: ""
 changes: []
 EOF
 
+# Reset main/review.yaml for the next release cycle
+cat >"$CHANGELOG_DIR/main/review.yaml" <<'EOF'
+todo: []
+validated: []
+EOF
+
 # Commit the changes and create the tag
 git add "$REPO_ROOT"
 git commit -m "release: $VERSION_TAG"
-git tag --force "$VERSION_TAG"
+git tag "$VERSION_TAG"
 
 # Push the changes
 git push --atomic origin main "$VERSION_TAG"

…e/src/content/docs/edge/guides/check.tsx …te/src/components/ui/CheckCircleIcon.tsxpackages/website/src/content/docs/edge/guides/check.tsx renamed to packages/website/src/components/ui/CheckCircleIcon.tsx packages/website/src/content/docs/edge/guides/check.tsx renamed to packages/website/src/components/ui/CheckCircleIcon.tsx

@@ -2,8 +2,8 @@ import Button from "@/components/ui/Button.tsx";
 import ContentBlockWithImage, {
   ContentBlockType,
 } from "@/components/ui/ContentBlockWithImage.tsx";
-import Check from "@/content/docs/main/guides/check.tsx";
-import Todo from "@/content/docs/main/guides/todo.tsx";
+import Check from "@/components/ui/CheckCircleIcon.tsx";
+import Todo from "@/components/ui/TodoIcon.tsx";
 
 export function RootDocumentLandingPage() {
   return (

…te/src/content/docs/edge/guides/todo.tsx …s/website/src/components/ui/TodoIcon.tsxpackages/website/src/content/docs/edge/guides/todo.tsx renamed to packages/website/src/components/ui/TodoIcon.tsx packages/website/src/content/docs/edge/guides/todo.tsx renamed to packages/website/src/components/ui/TodoIcon.tsx

@@ -298,7 +298,7 @@ for the following reasons:
 
 Ultimately, inbound traffic to clusters in the Panfactum Stack looks like the following: [^31]
 
-[^31]: For more information on VPCs and subnets, see [these docs.](http://localhost:3000/docs/main/concepts/networking/aws-primitives)
+[^31]: For more information on VPCs and subnets, see [these docs.](/docs/main/concepts/networking/aws-primitives)
 
 <MarkdownSVGImage src={ingressSVG} alt="Inbound network diagram" />
 
@@ -321,7 +321,7 @@ CoreDNS is extremely performant and provides one of the most stable implementati
 This allows your workloads to connect to domains like `my-service.my-namespace.svc.cluster.local`.
 
 We provide a module for deploying CoreDNS to Panfactum Stack clusters, [kube\_core\_dns](/docs/main/modules/kube_core_dns/overview),
-which is set up in [the bootstrapping guide.](http://localhost:3000/docs/main/guides/bootstrapping/internal-cluster-networking#deploy-coredns) [^20]
+which is set up in [the bootstrapping guide.](/docs/main/guides/bootstrapping/internal-cluster-networking#deploy-coredns) [^20]
 
 [^20]: Note that EKS also deploys CoreDNS to newly provisioned clusters. However, their implementation is lacking in several
     areas such as in monitoring and high-availability, so we supply our own.

packages/website/src/content/docs/edge/guides/index.tsx

@@ -102,7 +102,7 @@ To verify that everything was set up correctly:
 While the Event Bus will handle receiving and filtering events from your git repository, we still need to define
 what actions to take when events are received. This is done via Argo Workflows.
 
-We provide [several prebuilt Workflows](http://localhost:3000/docs/main/guides/addons/workflow-engine/prebuilt-workflows)
+We provide [several prebuilt Workflows](/docs/main/guides/addons/workflow-engine/prebuilt-workflows)
 that you can use for common CI / CD tasks.
 
 Right now, let's set up the IaC deployment workflow,

packages/website/src/content/docs/main/concepts/networking/cluster-networking/index.mdx

@@ -16,14 +16,20 @@ When you are ready to cut a new edge release:
 
 The release script will automatically perform the following actions:
 
-* Create the new release name based on today's date.
+* Create the new release name based on today's date (e.g., `edge.26-04-05`).
 
 * Copy all the unreleased documentation (under `packages/website/src/content/docs/main`) to the
-  edge documentation (under `packages/website/src/content/docs/edge`).
+  edge documentation (under `packages/website/src/content/docs/edge`), rewriting internal links
+  and version placeholders.
 
-* Update the Changelog headers to include the new release.
+* Copy the unreleased changelog (`changelog/main/log.yaml`) into a dated edge entry
+  (e.g., `changelog/edge/26-04-05/log.yaml`) and move any `upgrade.mdx` alongside it.
 
-* Create and push the appropriate release tag and commit.
+* Reset `changelog/main/log.yaml` and `changelog/main/review.yaml` for the next release cycle.
+
+* Update `constants.json` with the new edge version ref.
+
+* Create and push the release commit and git tag.
 
 ## Stable Releases