kitfly 0.2.1 → 0.2.4

package/src/__tests__/bundle.test.ts

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import {
 	buildBundleNav,
 	buildBundleSidebarHeader,
+	bundleSite,
 	fileToDataUri,
 	imageMime,
 	inlineLocalImages,
@@ -815,3 +816,197 @@ describe("buildBundleSidebarHeader", () => {
 		expect(html).toContain(`src="${logo}"`);
 	});
 });
+
+describe("bundleSite plugin integration", () => {
+	it("inlines latex plugin script when enabled", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Test"\nbrand:\n  name: "Test"\n  url: "/"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Bundle Math\n\n$E=mc^2$", "utf-8");
+		await writeFile(join(siteDir, "kitfly.plugins.yaml"), "plugins:\n  - latex@0.2.2\n", "utf-8");
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="latex@0.2.2"');
+		expect(html).toContain("const KATEX_JS_URL =");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js");
+		expect(html).toContain("cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css");
+	});
+
+	it("inlines slides-charts-lite plugin in slides mode", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "slides"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Charts Test"\nmode: "slides"\nbrand:\n  name: "Test"\n  url: "/"\nsections:\n  - name: Slides\n    path: slides\n',
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "slides", "deck.md"),
+			'# Deck\n\n```chart\nkind: line\nlabels: ["W1", "W2"]\ndata: [2, 3]\n```',
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - slides-charts-lite@0.2.2\n",
+			"utf-8",
+		);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="slides-charts-lite@0.2.2"');
+		expect(html).toContain("kitfly-chart-wrapper");
+	});
+
+	it("enforces planning-visuals fence contract in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+
+		const js = "console.log('planning visuals');";
+		const css = ".kitfly-planning-gantt{border:1px solid red;}";
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.css"), css, "utf-8");
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-03-03"
+baseUrl: ""
+plugins:
+  planning-visuals:
+    name: "Planning Visuals"
+    description: "Test planning visuals"
+    version: "0.2.4"
+    contract: "1"
+    kitfly: ">=0.2.4 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/planning-visuals.js"
+      css: "plugins-dist/planning-visuals.css"
+      assetSha256:
+        js: "sha256:4932eca4b9f9735541953e9be72a916d7e8a08213a28cc6e0a34899dab98b880"
+        css: "sha256:e73d687d58def8a6608ae51d1a1a09af6eaf2ec4c0b5d0849ebf260679e80e21"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Plan Test"\nbrand:\n  name: "Test"\n  url: "/"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "docs", "index.md"),
+			`# Plan
+
+:::gantt
+time-unit: week
+time-start: 2026-W10
+time-end: 2026-W12
+:::
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - planning-visuals@0.2.4\n",
+			"utf-8",
+		);
+
+		await expect(
+			bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" }),
+		).rejects.toThrow(/planning-visuals fence contract violations/i);
+	});
+
+	it("inlines footer logo image when configured", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "assets", "brand"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Footer Test"\nbrand:\n  name: "Test"\n  url: "/"\nfooter:\n  logo: "assets/brand/footer-logo.png"\n  logoAlt: "Footer Brand"\n  logoHeight: 24\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Footer Logo");
+		await writeFile(
+			join(siteDir, "assets", "brand", "footer-logo.png"),
+			Buffer.from(
+				"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl9x9kAAAAASUVORK5CYII=",
+				"base64",
+			),
+		);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('class="footer-logo-img"');
+		expect(html).toContain('src="data:image/png;base64,');
+		expect(html).not.toContain('src="assets/brand/footer-logo.png"');
+		expect(html).toContain('alt="Footer Brand"');
+		expect(html).toContain("max-height: 24px");
+	});
+
+	it("inlines footer logo from site-root-relative path outside assets", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "logos"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Footer Root Path Test"\nbrand:\n  name: "Test"\n  url: "/"\nfooter:\n  logo: "logos/footer.png"\n  logoAlt: "Footer Root Logo"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Footer Root Path");
+		await writeFile(
+			join(siteDir, "logos", "footer.png"),
+			Buffer.from(
+				"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl9x9kAAAAASUVORK5CYII=",
+				"base64",
+			),
+		);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('class="footer-logo-img"');
+		expect(html).toContain('src="data:image/png;base64,');
+		expect(html).not.toContain('src="logos/footer.png"');
+		expect(html).toContain('alt="Footer Root Logo"');
+	});
+
+	it("inlines light/dark variants for header and footer logos", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "assets", "brand"), { recursive: true });
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Dark Logos Test"\nbrand:\n  name: "Test"\n  url: "/"\n  logo: "assets/brand/logo.png"\n  logoDark: "assets/brand/logo-dark.png"\nfooter:\n  logo: "assets/brand/footer-logo.png"\n  logoDark: "assets/brand/footer-logo-dark.png"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(join(siteDir, "docs", "index.md"), "# Dark Logos");
+		const pixelPng = Buffer.from(
+			"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Wl9x9kAAAAASUVORK5CYII=",
+			"base64",
+		);
+		await writeFile(join(siteDir, "assets", "brand", "logo.png"), pixelPng);
+		await writeFile(join(siteDir, "assets", "brand", "logo-dark.png"), pixelPng);
+		await writeFile(join(siteDir, "assets", "brand", "footer-logo.png"), pixelPng);
+		await writeFile(join(siteDir, "assets", "brand", "footer-logo-dark.png"), pixelPng);
+
+		await bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" });
+
+		const html = await readFile(join(siteDir, "bundles", "bundle.html"), "utf-8");
+		expect(html).toContain('class="logo-img logo-light"');
+		expect(html).toContain('class="logo-img logo-dark"');
+		expect(html).toContain('class="footer-logo-img logo-light"');
+		expect(html).toContain('class="footer-logo-img logo-dark"');
+		expect(html).not.toContain('src="assets/brand/logo-dark.png"');
+		expect(html).not.toContain('src="assets/brand/footer-logo-dark.png"');
+	});
+});

package/src/__tests__/docs.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Tests for the kitfly docs command and embed-docs codegen.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { findSimilar } from "../commands/docs.ts";
+import { EMBEDDED_DOCS } from "../generated/embedded-docs.ts";
+
+describe("embed-docs codegen", () => {
+	it("generates embedded-docs.ts with entries", () => {
+		expect(existsSync("src/generated/embedded-docs.ts")).toBe(true);
+		expect(EMBEDDED_DOCS.length).toBeGreaterThan(0);
+	});
+
+	it("each entry has [slug, title, content] tuple", () => {
+		for (const entry of EMBEDDED_DOCS) {
+			expect(entry).toHaveLength(3);
+			const [slug, title, content] = entry;
+			expect(typeof slug).toBe("string");
+			expect(slug.length).toBeGreaterThan(0);
+			expect(typeof title).toBe("string");
+			expect(title.length).toBeGreaterThan(0);
+			expect(typeof content).toBe("string");
+			expect(content.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("slugs do not contain .md extension", () => {
+		for (const [slug] of EMBEDDED_DOCS) {
+			expect(slug).not.toMatch(/\.md$/);
+		}
+	});
+
+	it("slugs do not start with docs/ or content/", () => {
+		for (const [slug] of EMBEDDED_DOCS) {
+			expect(slug).not.toMatch(/^(docs|content)\//);
+		}
+	});
+
+	it("README/index files collapse to parent directory slug", () => {
+		// The docs/userguide/cli/README.md should become userguide/cli
+		const slugs = EMBEDDED_DOCS.map(([slug]) => slug);
+		expect(slugs).toContain("userguide/cli");
+		expect(slugs).not.toContain("userguide/cli/readme");
+		expect(slugs).not.toContain("userguide/cli/README");
+	});
+
+	it("excludes docs/releases/** and docs/decisions/**", () => {
+		const slugs = EMBEDDED_DOCS.map(([slug]) => slug);
+		for (const slug of slugs) {
+			expect(slug).not.toMatch(/^releases\//);
+			expect(slug).not.toMatch(/^decisions\//);
+		}
+	});
+
+	it("content has frontmatter stripped", () => {
+		for (const [, , content] of EMBEDDED_DOCS) {
+			// Content should not start with --- (frontmatter delimiter)
+			expect(content.trimStart()).not.toMatch(/^---\s*\n/);
+		}
+	});
+
+	it("entries are sorted by slug", () => {
+		const slugs = EMBEDDED_DOCS.map(([slug]) => slug);
+		const sorted = [...slugs].sort();
+		expect(slugs).toEqual(sorted);
+	});
+});
+
+describe("findSimilar", () => {
+	const slugs = [
+		"userguide/cli/dev",
+		"userguide/cli/build",
+		"userguide/cli/bundle",
+		"userguide/sharing",
+		"reference/configuration",
+		"reference/plugins",
+		"guide/getting-started",
+	];
+
+	it("finds prefix matches", () => {
+		const results = findSimilar("userguide/cli", slugs, 3);
+		expect(results.length).toBeGreaterThan(0);
+		expect(results.every((r) => r.startsWith("userguide/cli"))).toBe(true);
+	});
+
+	it("finds substring matches", () => {
+		const results = findSimilar("config", slugs, 3);
+		expect(results).toContain("reference/configuration");
+	});
+
+	it("returns at most max results", () => {
+		const results = findSimilar("userguide", slugs, 2);
+		expect(results.length).toBeLessThanOrEqual(2);
+	});
+
+	it("returns empty for no match", () => {
+		const results = findSimilar("nonexistent-slug-xyz", slugs, 3);
+		expect(results).toEqual([]);
+	});
+
+	it("prioritizes prefix over substring", () => {
+		const results = findSimilar("guide", slugs, 3);
+		// "guide/getting-started" is a prefix match, should come first
+		expect(results[0]).toBe("guide/getting-started");
+	});
+});
+
+describe("embed-docs script", () => {
+	it("regenerates from manifest without errors", () => {
+		const output = execSync("bun scripts/embed-docs.ts", { encoding: "utf-8" });
+		expect(output).toContain("Embedded");
+		expect(output).toContain("docs into src/generated/embedded-docs.ts");
+	});
+});

package/src/__tests__/fixtures/fences/planning-visuals/invalid/bad-month-format.md

@@ -0,0 +1,10 @@
+:::gantt
+time-unit: month
+time-start: "2026-13"
+time-end: "2026-10"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/marker-format-mismatch.md

@@ -0,0 +1,13 @@
+:::gantt
+time-unit: month
+time-start: "2026-04"
+time-end: "2026-10"
+markers:
+  - label: "Gate"
+    date: "2026-W20"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/milestone-format-mismatch.md

@@ -0,0 +1,13 @@
+:::gantt
+time-unit: month
+time-start: "2026-04"
+time-end: "2026-10"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+milestones:
+  - label: "Go-live"
+    date: "2026-W20"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/missing-tracks.md

@@ -0,0 +1,5 @@
+:::gantt
+time-unit: week
+time-start: "2026-W01"
+time-end: "2026-W06"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/track-reversed.md

@@ -0,0 +1,10 @@
+:::gantt
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W20"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-W18"
+    end: "2026-W15"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/markers-basic.md

@@ -0,0 +1,15 @@
+:::gantt
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W30"
+markers:
+  - label: "Go/No-Go"
+    date: "2026-W20"
+  - label: "Phase Gate"
+    date: "2026-W28"
+tracks:
+  - label: "Phase 1"
+    depth: 1
+    start: "2026-W14"
+    end: "2026-W24"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/markers-no-milestones.md

@@ -0,0 +1,13 @@
+:::gantt
+time-unit: month
+time-start: "2026-03"
+time-end: "2026-10"
+markers:
+  - label: "Funding Gate"
+    date: "2026-06"
+tracks:
+  - label: "Build"
+    depth: 1
+    start: "2026-03"
+    end: "2026-10"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/month-basic.md

@@ -0,0 +1,16 @@
+:::gantt
+label: "Rollout"
+time-unit: month
+time-start: "2026-04"
+time-end: "2026-10"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+  - label: "Wave 2"
+    depth: 1
+    start: "2026-08"
+    end: "2026-10"
+today: "2026-06"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/no-milestones.md

@@ -0,0 +1,10 @@
+:::gantt
+time-unit: week
+time-start: "2026-W01"
+time-end: "2026-W06"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-W01"
+    end: "2026-W04"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/week-basic.md

@@ -0,0 +1,20 @@
+:::gantt
+label: "Rollout"
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W20"
+max-depth: 2
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-W14"
+    end: "2026-W18"
+    status: active
+  - label: "Client A"
+    depth: 2
+    start: "2026-W15"
+    end: "2026-W17"
+milestones:
+  - label: "Sign-off"
+    date: "2026-W19"
+:::

package/src/__tests__/init.test.ts

@@ -9,8 +9,8 @@ import { existsSync } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { init } from "../commands/init.ts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { init, listAvailableTemplates } from "../commands/init.ts";
 import { defaultBranding, getTemplate, listTemplates, runTemplate } from "../templates/driver.ts";
 
 // ---------------------------------------------------------------------------
@@ -53,6 +53,7 @@ describe("template registry", () => {
 		expect(ids).toContain("minimal");
 		expect(ids).toContain("deck");
 		expect(ids).toContain("handbook");
+		expect(ids).toContain("brief");
 		expect(templates.length).toBeGreaterThanOrEqual(2);
 	});
 
@@ -66,6 +67,17 @@ describe("template registry", () => {
 	it("returns undefined for unknown template", () => {
 		expect(getTemplate("nonexistent")).toBeUndefined();
 	});
+
+	it("listAvailableTemplates output includes brief", () => {
+		const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+		try {
+			listAvailableTemplates();
+			const output = spy.mock.calls.map((call) => String(call[0] ?? "")).join("\n");
+			expect(output).toContain("brief");
+		} finally {
+			spy.mockRestore();
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -358,6 +370,16 @@ describe("init() entry point", () => {
 		expect(generatedExists(projectName, "CUSTOMIZING.md")).toBe(true);
 	});
 
+	it("creates a brief site when template flag is set", async () => {
+		await init(projectName, { template: "brief", git: false });
+
+		expect(generatedExists(projectName, "content/product/overview.md")).toBe(true);
+		expect(generatedExists(projectName, "content/use-cases/example-use-case.md")).toBe(true);
+		expect(generatedExists(projectName, "content/getting-started/requirements.md")).toBe(true);
+		expect(generatedExists(projectName, "content/reference/contacts.md")).toBe(true);
+		expect(generatedExists(projectName, "CUSTOMIZING.md")).toBe(true);
+	});
+
 	it("passes brand overrides through to template context", async () => {
 		await init(projectName, {
 			git: false,
@@ -439,6 +461,33 @@ describe("standalone mode", () => {
 	});
 });
 
+describe("ai-assist mode", () => {
+	const projectName = "test-brief-ai";
+
+	it("brief template writes AGENTS.md and brief-specific role files", async () => {
+		await runTemplate({
+			name: projectName,
+			template: "brief",
+			git: false,
+			aiAssist: true,
+		});
+
+		expect(generatedExists(projectName, "AGENTS.md")).toBe(true);
+		expect(generatedExists(projectName, "config/agentic/roles/devlead.yaml")).toBe(true);
+		expect(generatedExists(projectName, "config/agentic/roles/infoarch.yaml")).toBe(true);
+		expect(generatedExists(projectName, "config/agentic/roles/qa.yaml")).toBe(true);
+		expect(generatedExists(projectName, "config/agentic/roles/prodstrat.yaml")).toBe(true);
+		expect(generatedExists(projectName, "config/agentic/roles/advisor.yaml")).toBe(true);
+		expect(generatedExists(projectName, "config/agentic/roles/analyst.yaml")).toBe(false);
+		expect(generatedExists(projectName, "config/agentic/roles/prodmktg.yaml")).toBe(false);
+
+		const agents = await readGenerated(projectName, "AGENTS.md");
+		expect(agents).toContain("external audience brief");
+		expect(agents).toContain("informational and professional");
+		expect(agents).toContain("problem -> solution -> outcome");
+	});
+});
+
 // ---------------------------------------------------------------------------
 // Default Branding Derivation
 // ---------------------------------------------------------------------------

package/src/__tests__/latex-runtime.bun.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "bun:test";
+
+type LatexHooks = {
+	splitMath: (text: string) => Array<{ text?: string; math?: string; display?: boolean }>;
+	isCurrency: (expr: string) => boolean;
+	shouldTreatAsLiteralInline: (expr: string, text: string, closingIndex: number) => boolean;
+};
+
+async function loadHooks(): Promise<LatexHooks> {
+	// @ts-expect-error JS plugin helper file
+	await import("../../plugins-dist/latex-runtime.js");
+	const hooks = (globalThis as any).__kitflyLatexTest as LatexHooks | undefined;
+	if (!hooks) throw new Error("latex test hooks not found on globalThis");
+	return hooks;
+}
+
+test("latex: parses inline math", async () => {
+	const hooks = await loadHooks();
+	expect(hooks.splitMath("A $x^2$ value")).toEqual([
+		{ text: "A " },
+		{ math: "x^2", display: false },
+		{ text: " value" },
+	]);
+});
+
+test("latex: treats $5-$10 as literal currency range", async () => {
+	const hooks = await loadHooks();
+	expect(hooks.splitMath("$5-$10")).toEqual([{ text: "$5-$10" }]);
+});
+
+test("latex: currency helper matches dashed ranges", async () => {
+	const hooks = await loadHooks();
+	expect(hooks.isCurrency("5-10")).toBe(true);
+	expect(hooks.isCurrency("5 to 10")).toBe(true);
+});

package/src/__tests__/planning-visuals-fence-contract.test.ts

@@ -0,0 +1,28 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { validatePlanningVisualsFences } from "../shared.ts";
+
+const FIXTURES = join(__dirname, "fixtures", "fences", "planning-visuals");
+
+describe("planning-visuals fence contract", () => {
+	it("accepts valid fixtures", async () => {
+		const dir = join(FIXTURES, "valid");
+		const files = await readdir(dir);
+		for (const f of files) {
+			const md = await readFile(join(dir, f), "utf-8");
+			const diags = validatePlanningVisualsFences(md);
+			expect(diags, `${f} should be valid`).toHaveLength(0);
+		}
+	});
+
+	it("rejects invalid fixtures", async () => {
+		const dir = join(FIXTURES, "invalid");
+		const files = await readdir(dir);
+		for (const f of files) {
+			const md = await readFile(join(dir, f), "utf-8");
+			const diags = validatePlanningVisualsFences(md);
+			expect(diags.length, `${f} should be invalid`).toBeGreaterThan(0);
+		}
+	});
+});