From a6b974f3c62ccad610e162fc2dd4d546c514164b Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 11:51:25 -0500
Subject: [PATCH 1/9] Set SITE_URL for smoke container

---
 .github/workflows/pages.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 8ebb74a..f393095 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -99,6 +99,7 @@ jobs:
       - name: Start Unfold container
         run: |
           docker run -d --rm -p 3000:3000 \
+            -e SITE_URL=http://localhost:3000 \
             -e VAULT_PATH=vault \
             -v "$PWD/vault:/workspaces/schema-nodes/vault" \
             --name unfold-smoke \

From 31f233e07b1868b8c81e9e4a01a95ea0c5ce4379 Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 11:53:37 -0500
Subject: [PATCH 2/9] Remove duplicate getSiteDest

---
 src/unfold/site/site.ts | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/unfold/site/site.ts b/src/unfold/site/site.ts
index e513502..fe0dc7f 100644
--- a/src/unfold/site/site.ts
+++ b/src/unfold/site/site.ts
@@ -56,9 +56,6 @@ const getVaultPath = (): string => {
   return override;
 };
 
-const getSiteDest = (): string =>
-  Deno.env.get("SITE_OUTPUT_DIR")?.trim() || ".unfold/site";
-
 const getSiteDest = (): string =>
   Deno.env.get("SITE_OUTPUT_DIR")?.trim() || ".unfold/site";
 

From f7f410f0967d500d837300d8b81093bc08c1d72b Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:00:13 -0500
Subject: [PATCH 3/9] Skip JSON-LD validation when vault is empty

---
 src/unfold/pipeline/validate.ts      | 13 +++++++++++++
 src/unfold/pipeline/validate_test.ts | 27 +++++++++++++++++++++++++--
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/src/unfold/pipeline/validate.ts b/src/unfold/pipeline/validate.ts
index 1717f83..ded7a0b 100644
--- a/src/unfold/pipeline/validate.ts
+++ b/src/unfold/pipeline/validate.ts
@@ -111,6 +111,19 @@ export const runValidate = async (
     await deps.writeError(errorLines.join("\n"));
     throw new Error("JSON-LD load failed");
   }
+  if (nodes.length === 0) {
+    const lines = [
+      `JSON-LD validation skipped (mode: ${mode}):`,
+      `  - no JSON-LD nodes found in ${vaultPath}`,
+      "Hint: export JSON-LD into the vault or set VAULT_BASE_URL.",
+    ];
+    if (mode === "strict") {
+      await deps.writeError(lines.join("\n"));
+      throw new Error("JSON-LD validation failed");
+    }
+    await deps.writeWarning(lines.join("\n"));
+    return;
+  }
 
   if (mode === "strict") {
     const jsonSchemaErrors = await deps.validateNodesJsonSchema(nodes);
diff --git a/src/unfold/pipeline/validate_test.ts b/src/unfold/pipeline/validate_test.ts
index bf6dacf..273c874 100644
--- a/src/unfold/pipeline/validate_test.ts
+++ b/src/unfold/pipeline/validate_test.ts
@@ -1,14 +1,22 @@
 import { assert, assertRejects } from "@std/assert";
-import { ValidationError } from "../inputs/jsonld/types.ts";
+import { ValidationError, type VaultNode } from "../inputs/jsonld/types.ts";
 import { ORPHAN_REACHABILITY_PREFIX } from "../inputs/jsonld/validator_reachability.ts";
 import { runValidate, type ValidationDeps } from "./validate.ts";
 
+const SAMPLE_NODES: VaultNode[] = [
+  {
+    "@type": "Catalog",
+    "@id": "https://example.org/catalog",
+    _source: { file: "vault/catalog.jsonld", path: "vault/catalog.jsonld" },
+  },
+];
+
 const createBaseDeps = (
   overrides: Partial<ValidationDeps> = {},
 ): Partial<ValidationDeps> => ({
   prepareVault: async () => {},
   getVaultPath: () => "/vault",
-  loadVault: async () => ({ nodes: [], errors: [] }),
+  loadVault: async () => ({ nodes: SAMPLE_NODES, errors: [] }),
   validateNodesJsonSchema: async () => [],
   validateNodes: async () => [],
   loadShapes: async () => ({ shapes: [] }),
@@ -22,6 +30,21 @@ const createBaseDeps = (
   ...overrides,
 });
 
+Deno.test("runValidate - dev mode warns when no JSON-LD nodes found", async () => {
+  const warnings: string[] = [];
+  const deps = createBaseDeps({
+    loadVault: async () => ({ nodes: [], errors: [] }),
+    writeWarning: async (text: string) => {
+      warnings.push(text);
+    },
+  });
+
+  await runValidate({ mode: "dev", deps });
+
+  assert(warnings.length === 1);
+  assert(warnings[0].includes("no JSON-LD nodes found"));
+});
+
 Deno.test("runValidate - dev mode warns on orphan reachability", async () => {
   const warnings: string[] = [];
   const deps = createBaseDeps({

From 50a646def990436be194b00ccc4161b2042978fe Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:01:08 -0500
Subject: [PATCH 4/9] Gate smoke job on build

---
 .github/workflows/pages.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index f393095..4cd550d 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -78,6 +78,7 @@ jobs:
 
   container-smoke:
     runs-on: ubuntu-latest
+    needs: build
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -117,7 +118,7 @@ jobs:
 
   publish-image:
     runs-on: ubuntu-latest
-    needs: container-smoke
+    needs: [build, container-smoke]
     steps:
       - name: Checkout
         uses: actions/checkout@v4

From f9eb928369c24f6dac64e3a784b13e8b6c7cf180 Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:02:18 -0500
Subject: [PATCH 5/9] Preserve smoke container for logs

---
 .github/workflows/pages.yml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 4cd550d..80cdd2f 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -99,22 +99,28 @@ jobs:
 
       - name: Start Unfold container
         run: |
-          docker run -d --rm -p 3000:3000 \
+          docker run -d -p 3000:3000 \
             -e SITE_URL=http://localhost:3000 \
             -e VAULT_PATH=vault \
             -v "$PWD/vault:/workspaces/schema-nodes/vault" \
             --name unfold-smoke \
             unfold-dev-ci:latest
           for i in $(seq 1 30); do
+            running=$(docker inspect -f '{{.State.Running}}' unfold-smoke 2>/dev/null || echo "false")
+            if [ "$running" != "true" ]; then
+              echo "Container exited before health check passed."
+              docker logs unfold-smoke || true
+              exit 1
+            fi
             curl -fsS http://localhost:3000/healthz >/dev/null 2>&1 && exit 0
             sleep 1
           done
-          docker logs unfold-smoke
+          docker logs unfold-smoke || true
           exit 1
 
       - name: Stop Unfold container
         if: always()
-        run: docker stop unfold-smoke
+        run: docker rm -f unfold-smoke || true
 
   publish-image:
     runs-on: ubuntu-latest

From 9f3f3f9628fc7cff12c9967d8ac9c78fd8bf0e19 Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:06:17 -0500
Subject: [PATCH 6/9] Fix AI exporters test path

---
 .github/workflows/pages.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 80cdd2f..183736c 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -65,7 +65,7 @@ jobs:
           VAULT_PATH: vault
 
       - name: Validate AI exports
-        run: deno test -A src/unfold/tests/exporters_ai_test.ts
+        run: deno test -A src/unfold/exporters/exporters_ai_test.ts
         env:
           SITE_URL: ${{ steps.site.outputs.site_url }}
           SITE_OUTPUT_DIR: .unfold/site

From 60afe82890eb7022c9591fb2f4852b3b856d938e Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:30:14 -0500
Subject: [PATCH 7/9] Fix JSON-LD site build pipeline

---
 src/unfold/exporters/llms.ts               |  2 +
 src/unfold/exporters/mcp.ts                |  4 ++
 src/unfold/inputs/vault/load_vault.ts      |  2 +-
 src/unfold/renderers/lume/jsonld_loader.ts | 38 +++++++++------
 src/unfold/site/site.ts                    | 56 ++++++++++++++++++----
 5 files changed, 78 insertions(+), 24 deletions(-)

diff --git a/src/unfold/exporters/llms.ts b/src/unfold/exporters/llms.ts
index 381ebdf..251f4c6 100644
--- a/src/unfold/exporters/llms.ts
+++ b/src/unfold/exporters/llms.ts
@@ -79,6 +79,8 @@ export const buildLlmsTxt = async (
       const url = resolveCanonical(page, siteUrl);
       const title = normalizeText(
         page.document?.querySelector("title")?.textContent,
+      ) || normalizeText(
+        typeof page.data?.title === "string" ? page.data.title : "",
       );
       if (!url) {
         return null;
diff --git a/src/unfold/exporters/mcp.ts b/src/unfold/exporters/mcp.ts
index 6816387..ba0ba24 100644
--- a/src/unfold/exporters/mcp.ts
+++ b/src/unfold/exporters/mcp.ts
@@ -108,11 +108,15 @@ export const buildMcpBundle = async (
       const url = resolveCanonical(page, siteUrl);
       const title = normalizeText(
         page.document?.querySelector("title")?.textContent,
+      ) || normalizeText(
+        typeof page.data?.title === "string" ? page.data.title : "",
       );
       const description = normalizeText(
         page.document?.querySelector('meta[name="description"]')?.getAttribute(
           "content",
         ),
+      ) || normalizeText(
+        typeof page.data?.description === "string" ? page.data.description : "",
       );
       if (!url || !title) {
         return null;
diff --git a/src/unfold/inputs/vault/load_vault.ts b/src/unfold/inputs/vault/load_vault.ts
index 3eadfe9..91d33ce 100644
--- a/src/unfold/inputs/vault/load_vault.ts
+++ b/src/unfold/inputs/vault/load_vault.ts
@@ -1,5 +1,5 @@
 import { walk } from "@std/fs";
-import { relative } from "@std/path";
+import { isAbsolute, join, relative, toFileUrl } from "@std/path";
 import { vaultConfig, DEFAULT_VAULT_DIRS } from "./vault_config.ts";
 
 export const loadVaultRoot = (): URL => {
diff --git a/src/unfold/renderers/lume/jsonld_loader.ts b/src/unfold/renderers/lume/jsonld_loader.ts
index bde885f..c6e8dd4 100644
--- a/src/unfold/renderers/lume/jsonld_loader.ts
+++ b/src/unfold/renderers/lume/jsonld_loader.ts
@@ -19,20 +19,20 @@ type LoaderFunction = (path: string) => Promise<PageData>;
  * Extract page data from a JSON-LD node
  * Maps JSON-LD properties to Lume page data
  */
-function extractPageData(node: JsonLdNode): PageData {
+function extractPageData(node: JsonLdNode, sourcePath: string): PageData {
   const extractedDate = extractDate(node);
 
   const data: PageData = {
     // Required Lume fields
-    url: extractUrl(node),
-    title: extractTitle(node),
+    url: extractUrl(node, sourcePath),
+    title: extractTitle(node, sourcePath),
     date: extractedDate || new Date(), // Lume requires Date, not undefined
 
     // Optional fields
     description: extractString(node, "description"),
 
     // Content
-    content: extractContent(node),
+    content: extractContent(node, sourcePath),
 
     // JSON-LD metadata (full node for <script type="application/ld+json">)
     // The layout template will inject this into the page head
@@ -40,7 +40,7 @@ function extractPageData(node: JsonLdNode): PageData {
 
     // Metas for SEO
     metas: {
-      title: extractTitle(node),
+      title: extractTitle(node, sourcePath),
       description: extractString(node, "description"),
       type: "article",
     },
@@ -58,7 +58,7 @@ function extractPageData(node: JsonLdNode): PageData {
  * Extract URL from @id
  * Convert @id IRI to Lume-friendly URL path
  */
-function extractUrl(node: JsonLdNode): string {
+function extractUrl(node: JsonLdNode, sourcePath: string): string {
   const id = node["@id"];
   if (!id) {
     throw new Error(`Node missing @id: ${JSON.stringify(node)}`);
@@ -67,17 +67,17 @@ function extractUrl(node: JsonLdNode): string {
   try {
     const url = new URL(id);
     // Return pathname (e.g., /pages/hello from https://example.org/pages/hello)
-    return url.pathname + url.hash;
+    const path = url.pathname + url.hash;
+    return path.startsWith("/") ? path : urlFromPath(sourcePath);
   } catch {
-    // If not a valid URL, use as-is
-    return id;
+    return urlFromPath(sourcePath);
   }
 }
 
 /**
  * Extract title from various JSON-LD properties
  */
-function extractTitle(node: JsonLdNode): string {
+function extractTitle(node: JsonLdNode, sourcePath: string): string {
   // Try common title properties
   const candidates = [
     node.title,
@@ -95,7 +95,7 @@ function extractTitle(node: JsonLdNode): string {
   }
 
   // Fallback to @id
-  return extractUrl(node);
+  return extractUrl(node, sourcePath);
 }
 
 /**
@@ -142,7 +142,7 @@ function extractDate(node: JsonLdNode): Date | undefined {
 /**
  * Extract content from the node
  */
-function extractContent(node: JsonLdNode): string {
+function extractContent(node: JsonLdNode, sourcePath: string): string {
   // Check for explicit content properties
   const content = extractString(
     node,
@@ -168,8 +168,8 @@ function extractContent(node: JsonLdNode): string {
           if (keys.length === 0) {
             return ""; // Just a reference, skip it
           }
-          const sectionTitle = extractTitle(partNode);
-          const sectionContent = extractContent(partNode);
+          const sectionTitle = extractTitle(partNode, sourcePath);
+          const sectionContent = extractContent(partNode, sourcePath);
           if (sectionContent) {
             return `<section>\n<h2>${sectionTitle}</h2>\n${sectionContent}\n</section>`;
           }
@@ -192,6 +192,14 @@ function extractContent(node: JsonLdNode): string {
   return "";
 }
 
+const urlFromPath = (path: string): string => {
+  const normalized = path.replaceAll("\\", "/");
+  const withoutExt = normalized.endsWith(".jsonld")
+    ? normalized.slice(0, -7)
+    : normalized;
+  return withoutExt.startsWith("/") ? withoutExt : `/${withoutExt}`;
+};
+
 /**
  * Lume loader for .jsonld files
  */
@@ -224,7 +232,7 @@ export default function (): LoaderFunction {
       return {} as PageData; // Return empty page data to skip this file
     }
 
-    const data = extractPageData(mainNode);
+    const data = extractPageData(mainNode, path);
 
     // Store all nodes for potential use
     data.allNodes = nodes;
diff --git a/src/unfold/site/site.ts b/src/unfold/site/site.ts
index fe0dc7f..19d04bc 100644
--- a/src/unfold/site/site.ts
+++ b/src/unfold/site/site.ts
@@ -19,6 +19,38 @@ import { siteBuildConfig } from "./site_build_config.ts";
 import { vaultConfig } from "../inputs/vault/vault_config.ts";
 const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 
+const normalizePages = (pages: Page[] | Iterable<Page>): Page[] =>
+  Array.isArray(pages) ? pages : Array.from(pages);
+
+const normalizeJsonldPath = (url: string): string => {
+  const noFragment = url.split("#")[0] ?? url;
+  const noQuery = noFragment.split("?")[0] ?? noFragment;
+  const trimmed = noQuery.replace(/^\/+/, "").replace(/\/$/, "");
+  if (!trimmed) {
+    return "index";
+  }
+  return trimmed.endsWith(".html") ? trimmed.slice(0, -5) : trimmed;
+};
+
+const writeJsonldPages = async (
+  site: ReturnType<typeof lume>,
+  pages: Page[],
+): Promise<void> => {
+  for (const page of pages) {
+    const url = page.data?.url;
+    const rawJsonld = page.data?.jsonld;
+    if (typeof url !== "string" || !rawJsonld) {
+      continue;
+    }
+    const relPath = normalizeJsonldPath(url);
+    const outputPath = site.dest(join("jsonld", `${relPath}.jsonld`));
+    await Deno.mkdir(dirname(outputPath), { recursive: true });
+    const jsonld =
+      typeof rawJsonld === "string" ? JSON.parse(rawJsonld) : rawJsonld;
+    await Deno.writeTextFile(outputPath, JSON.stringify(jsonld, null, 2));
+  }
+};
+
 const getSiteUrl = (): string => siteBuildConfig.siteUrl;
 
 const getSiteBasePath = () => {
@@ -36,15 +68,11 @@ const getVaultPath = (): string => {
   const override = Deno.env.get("VAULT_PATH")?.trim();
   if (!override) {
     const workspaceRoot = getWorkspaceRoot().replace(/\/$/, "");
-    try {
-      const stat = Deno.statSync(join(workspaceRoot, "vault"));
-      if (stat.isDirectory) {
-        return "vault";
-      }
-    } catch {
-      // Fall through to repo root.
+    const resolved = vaultConfig.vaultPath;
+    if (isAbsolute(resolved) && resolved.startsWith(`${workspaceRoot}/`)) {
+      return relative(workspaceRoot, resolved);
     }
-    return ".";
+    return resolved;
   }
   if (isAbsolute(override)) {
     const workspaceRoot = getWorkspaceRoot().replace(/\/$/, "");
@@ -64,11 +92,21 @@ export const createSite = (): ReturnType<typeof lume> => {
   const basePath = getSiteBasePath();
   const workspaceRoot = getWorkspaceRoot();
   const vaultPath = getVaultPath();
+  const layoutPath = getLayoutPath();
   const normalizedWorkspaceRoot = workspaceRoot.replace(/\/$/, "");
   const srcPath = vaultPath.startsWith(`${normalizedWorkspaceRoot}/`)
     ? relative(normalizedWorkspaceRoot, vaultPath)
     : vaultPath;
   const destPath = getSiteDest();
+  const srcRoot = isAbsolute(srcPath) ? srcPath : join(workspaceRoot, srcPath);
+  const includesDir = join(srcRoot, "_includes");
+  const layoutTarget = join(includesDir, "layout.tmpl.ts");
+  try {
+    Deno.statSync(layoutTarget);
+  } catch {
+    Deno.mkdirSync(includesDir, { recursive: true });
+    Deno.copyFileSync(layoutPath, layoutTarget);
+  }
 
   const site = lume({
     cwd: workspaceRoot,
@@ -79,6 +117,8 @@ export const createSite = (): ReturnType<typeof lume> => {
       debounce: DEFAULT_WATCH_DEBOUNCE_MS,
     },
   });
+  site.loadPages([".jsonld"], jsonLdLoader());
+  site.data("layout", "layout.tmpl.ts");
 
   const ignorePrefixes = [
     ".cursor/",

From e061cd5bf8e5ac26c4d7df75fba094b909f86d29 Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:46:18 -0500
Subject: [PATCH 8/9] Skip deploy on non-main branches

---
 .github/workflows/pages.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 183736c..1b2009a 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -147,6 +147,7 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     needs: build
+    if: github.ref == 'refs/heads/main'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

From 7cbebb7835d7ad0805ac3f2b36cd87a5834cb39f Mon Sep 17 00:00:00 2001
From: Robert DeLanghe <1240090+bdelanghe@users.noreply.github.com>
Date: Thu, 5 Feb 2026 13:05:28 -0500
Subject: [PATCH 9/9] Address PR review notes

---
 .github/workflows/pages.yml |  1 +
 src/unfold/site/site.ts     | 12 +++++++++---
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 1b2009a..ef38d96 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -125,6 +125,7 @@ jobs:
   publish-image:
     runs-on: ubuntu-latest
     needs: [build, container-smoke]
+    if: github.ref == 'refs/heads/main'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
diff --git a/src/unfold/site/site.ts b/src/unfold/site/site.ts
index 19d04bc..5317d56 100644
--- a/src/unfold/site/site.ts
+++ b/src/unfold/site/site.ts
@@ -23,8 +23,8 @@ const normalizePages = (pages: Page[] | Iterable<Page>): Page[] =>
   Array.isArray(pages) ? pages : Array.from(pages);
 
 const normalizeJsonldPath = (url: string): string => {
-  const noFragment = url.split("#")[0] ?? url;
-  const noQuery = noFragment.split("?")[0] ?? noFragment;
+  const noFragment = url.split("#")[0];
+  const noQuery = noFragment.split("?")[0];
   const trimmed = noQuery.replace(/^\/+/, "").replace(/\/$/, "");
   if (!trimmed) {
     return "index";
@@ -105,7 +105,13 @@ export const createSite = (): ReturnType<typeof lume> => {
     Deno.statSync(layoutTarget);
   } catch {
     Deno.mkdirSync(includesDir, { recursive: true });
-    Deno.copyFileSync(layoutPath, layoutTarget);
+    try {
+      Deno.copyFileSync(layoutPath, layoutTarget);
+    } catch (error) {
+      if (!(error instanceof Deno.errors.AlreadyExists)) {
+        throw error;
+      }
+    }
   }
 
   const site = lume({