From 179672f84fdbaa40a7d67ba2b6e726ed4c49fe7f Mon Sep 17 00:00:00 2001
From: Gautam Raj <ashragautam25@gmail.com>
Date: Wed, 1 Jul 2026 03:18:01 +0530
Subject: [PATCH] feat(portfolio): enhance template details with FAQs and
 guidelines, refactor template loading

---
 apps/portfolio/app/templates/[id]/page.tsx    |  19 ++++
 apps/portfolio/components/DraftPreview.tsx    |  13 ++-
 .../components/LivePortfolioPreview.tsx       |  11 +-
 .../templates/components/TemplateBestFit.tsx  |  21 ++++
 .../components/TemplateDetailContainer.tsx    |   5 +-
 .../templates/components/TemplateFaqs.tsx     | 104 ++++++++++++++++++
 .../components/TemplateFullSystemSpec.tsx     |  67 +++++++++--
 .../components/TemplateGuidelines.tsx         |  59 ++++++++++
 .../templates/data/template-details.ts        |  74 +++++--------
 apps/portfolio/lib/portfolio.ts               |   7 +-
 apps/portfolio/templates/catalog/templates.ts |  40 +++----
 apps/server/src/polyfills.ts                  |  20 +++-
 apps/server/src/services/aiPolicy.ts          |  10 +-
 apps/server/src/services/atsAiPolicy.ts       |  10 +-
 scripts/mock-template-library.mjs             |  64 ++++++++++-
 15 files changed, 399 insertions(+), 125 deletions(-)
 create mode 100644 apps/portfolio/features/templates/components/TemplateFaqs.tsx
 create mode 100644 apps/portfolio/features/templates/components/TemplateGuidelines.tsx

diff --git a/apps/portfolio/app/templates/[id]/page.tsx b/apps/portfolio/app/templates/[id]/page.tsx
index 7c41f08b..2b754e69 100644
--- a/apps/portfolio/app/templates/[id]/page.tsx
+++ b/apps/portfolio/app/templates/[id]/page.tsx
@@ -89,6 +89,25 @@ const PortfolioTemplateDetailPage = async ({ params }: PageProps) => {
         type="application/ld+json"
         dangerouslySetInnerHTML={{ __html: JSON.stringify(templateSchema) }}
       />
+      {details.faqs && (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify({
+              "@context": "https://schema.org",
+              "@type": "FAQPage",
+              mainEntity: details.faqs.map((faq) => ({
+                "@type": "Question",
+                name: faq.question,
+                acceptedAnswer: {
+                  "@type": "Answer",
+                  text: faq.answer,
+                },
+              })),
+            }),
+          }}
+        />
+      )}
 
       <div className="text-ink-2 bg-paper min-h-dvh overflow-x-clip pt-28 font-['Outfit','Avenir_Next','Trebuchet_MS',sans-serif]">
         <TemplatesNavigation showPricing={true} backHref="/templates" backLabel="All templates" />
diff --git a/apps/portfolio/components/DraftPreview.tsx b/apps/portfolio/components/DraftPreview.tsx
index e0ae8705..366047c5 100644
--- a/apps/portfolio/components/DraftPreview.tsx
+++ b/apps/portfolio/components/DraftPreview.tsx
@@ -4,11 +4,14 @@ import { useEffect } from "react";
 import dynamic from "next/dynamic";
 
 import { demoPortfolio, type TemplateId } from "@/lib/portfolio";
+import { templateLoaders } from "@/template-library/registry";
 
-const templates = {
-  signal: dynamic(() => import("@/template-library/signal/SignalTemplate")),
-  atelier: dynamic(() => import("@/template-library/atelier/AtelierTemplate")),
-};
+const templates = Object.fromEntries(
+  Object.entries(templateLoaders).map(([id, loader]) => [id, dynamic(loader)]),
+) as Record<
+  TemplateId,
+  React.ComponentType<{ project: import("@/lib/portfolio").PortfolioContent }>
+>;
 
 export function DraftPreview({ templateId }: { templateId: TemplateId }) {
   const Template = templates[templateId];
@@ -75,6 +78,8 @@ export function DraftPreview({ templateId }: { templateId: TemplateId }) {
     };
   }, []);
 
+  if (!Template) return null;
+
   return (
     <div className="select-none" style={{ userSelect: "none", WebkitUserSelect: "none" }}>
       <Template project={{ ...demoPortfolio, templateId }} />
diff --git a/apps/portfolio/components/LivePortfolioPreview.tsx b/apps/portfolio/components/LivePortfolioPreview.tsx
index 7a265529..db9d879a 100644
--- a/apps/portfolio/components/LivePortfolioPreview.tsx
+++ b/apps/portfolio/components/LivePortfolioPreview.tsx
@@ -3,12 +3,12 @@
 import dynamic from "next/dynamic";
 import { useEffect, useState } from "react";
 
-import { parsePortfolioContent, type PortfolioContent } from "@/lib/portfolio";
+import { parsePortfolioContent, type PortfolioContent, type TemplateId } from "@/lib/portfolio";
+import { templateLoaders } from "@/template-library/registry";
 
-const templates = {
-  signal: dynamic(() => import("@/template-library/signal/SignalTemplate")),
-  atelier: dynamic(() => import("@/template-library/atelier/AtelierTemplate")),
-};
+const templates = Object.fromEntries(
+  Object.entries(templateLoaders).map(([id, loader]) => [id, dynamic(loader)]),
+) as Record<TemplateId, React.ComponentType<{ project: PortfolioContent }>>;
 
 export function LivePortfolioPreview({ initialContent }: { initialContent: PortfolioContent }) {
   const [content, setContent] = useState(initialContent);
@@ -29,6 +29,7 @@ export function LivePortfolioPreview({ initialContent }: { initialContent: Portf
   }, []);
 
   const Template = templates[content.templateId];
+  if (!Template) return null;
 
   return <Template project={content} />;
 }
diff --git a/apps/portfolio/features/templates/components/TemplateBestFit.tsx b/apps/portfolio/features/templates/components/TemplateBestFit.tsx
index 3248328c..417fd0b8 100644
--- a/apps/portfolio/features/templates/components/TemplateBestFit.tsx
+++ b/apps/portfolio/features/templates/components/TemplateBestFit.tsx
@@ -36,6 +36,27 @@ const TemplateBestFit = ({
           <div className="bg-accent border-accent text-accent-ink rounded-3xl border p-5 text-sm leading-6 font-semibold sm:col-span-2">
             Motion direction: {details.motion}
           </div>
+
+          {details.system?.targetProfessions && (
+            <div className="mt-8 border-t border-white/10 pt-8 sm:col-span-2">
+              <h3 className="mb-4 text-lg font-bold tracking-tight text-white">
+                Suitability by target role
+              </h3>
+              <div className="grid gap-3 sm:grid-cols-2 md:grid-cols-3">
+                {details.system.targetProfessions.map((prof) => (
+                  <div
+                    key={prof.role}
+                    className="rounded-2xl border border-white/10 bg-white/2 p-4.5"
+                  >
+                    <h4 className="text-accent dark:text-accent mb-1.5 animate-pulse font-mono text-[10px] font-bold tracking-wider uppercase">
+                      {prof.role}
+                    </h4>
+                    <p className="text-xs leading-relaxed text-white/70">{prof.why}</p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
         </div>
       </div>
     </section>
diff --git a/apps/portfolio/features/templates/components/TemplateDetailContainer.tsx b/apps/portfolio/features/templates/components/TemplateDetailContainer.tsx
index cce20bf1..1dc3176d 100644
--- a/apps/portfolio/features/templates/components/TemplateDetailContainer.tsx
+++ b/apps/portfolio/features/templates/components/TemplateDetailContainer.tsx
@@ -7,6 +7,7 @@ import type { TemplateDetails } from "../data/template-details";
 import type { TemplateSummary } from "@/templates/catalog/templates";
 
 import TemplateCta from "./TemplateCta";
+import TemplateFaqs from "./TemplateFaqs";
 import TemplateBestFit from "./TemplateBestFit";
 import TemplateDetailHero from "./TemplateDetailHero";
 import TemplateStyleGuide from "./TemplateStyleGuide";
@@ -52,7 +53,7 @@ const TemplateDetailContainer = ({ template, details }: ContainerProps) => {
       <div ref={specAnchorRef} className="scroll-mt-28" />
 
       <div className={devMode ? "block" : "hidden"}>
-        <TemplateFullSystemSpec details={details} />
+        <TemplateFullSystemSpec details={details} templateId={template.id} />
       </div>
 
       <div className={devMode ? "hidden" : "block"}>
@@ -83,6 +84,8 @@ const TemplateDetailContainer = ({ template, details }: ContainerProps) => {
 
       <TemplateBestFit template={template} details={details} />
 
+      {details.faqs && <TemplateFaqs faqs={details.faqs} templateName={template.name} />}
+
       <TemplateCta template={template} />
 
       <div className="fixed bottom-8 left-8 z-80 hidden md:block">
diff --git a/apps/portfolio/features/templates/components/TemplateFaqs.tsx b/apps/portfolio/features/templates/components/TemplateFaqs.tsx
new file mode 100644
index 00000000..66e731d2
--- /dev/null
+++ b/apps/portfolio/features/templates/components/TemplateFaqs.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import { useState } from "react";
+import { HelpCircle, ChevronDown } from "lucide-react";
+
+type FaqItem = {
+  question: string;
+  answer: string;
+};
+
+type FaqProps = {
+  faqs: FaqItem[];
+  templateName: string;
+};
+
+export default function TemplateFaqs({ faqs, templateName }: FaqProps) {
+  const [openIndex, setOpenIndex] = useState<number | null>(null);
+
+  const toggle = (idx: number) => {
+    setOpenIndex((prev) => (prev === idx ? null : idx));
+  };
+
+  if (!faqs || faqs.length === 0) return null;
+
+  return (
+    <section className="mx-auto w-[min(1200px,calc(100%-48px))] pb-24">
+      <div className="border-ink-2 bg-panel rounded-4xl border-2 p-6 shadow-[14px_16px_0_rgba(37,99,235,0.12)] sm:p-8">
+        <div className="grid gap-8 lg:grid-cols-[0.85fr_1.15fr]">
+          <div>
+            <p className="text-accent flex items-center gap-2 text-xs font-bold tracking-[0.16em] uppercase">
+              <HelpCircle size={14} className="animate-pulse" /> Frequently Asked Questions
+            </p>
+
+            <h2 className="text-ink-2 mt-4 max-w-xl text-[clamp(2.8rem,5vw,5.5rem)] leading-[1.05] font-bold tracking-tighter">
+              Got questions about {templateName}?
+            </h2>
+
+            <p className="text-ink-2/62 mt-5 max-w-md text-sm leading-7">
+              Explore answers to common questions about this layout, design styling choices, and
+              performance optimizations.
+            </p>
+          </div>
+
+          <div className="space-y-3.5">
+            {faqs.map((faq, idx) => {
+              const isOpen = openIndex === idx;
+              const titleId = `template-faq-title-${idx}`;
+              const contentId = `template-faq-content-${idx}`;
+
+              return (
+                <article
+                  key={idx}
+                  className={`bg-paper rounded-2xl border-2 transition-all duration-300 ${
+                    isOpen
+                      ? "border-accent shadow-[6px_8px_0_rgba(37,99,235,0.06)]"
+                      : "border-ink-2/10 hover:border-ink-2/25 shadow-sm"
+                  }`}
+                >
+                  <button
+                    type="button"
+                    onClick={() => toggle(idx)}
+                    aria-expanded={isOpen}
+                    aria-controls={contentId}
+                    className="flex w-full cursor-pointer items-center justify-between gap-4 p-5 text-left transition-transform active:scale-[0.99] sm:p-6"
+                  >
+                    <h3
+                      id={titleId}
+                      className="text-ink-2 text-sm font-bold tracking-tight sm:text-base"
+                    >
+                      {faq.question}
+                    </h3>
+
+                    <span
+                      className={`bg-panel border-ink-2/10 flex size-7 shrink-0 items-center justify-center rounded-full border transition-all duration-300 ${
+                        isOpen
+                          ? "text-accent bg-accent/8 border-accent/20 rotate-180"
+                          : "text-ink-2/45"
+                      }`}
+                    >
+                      <ChevronDown className="size-4" />
+                    </span>
+                  </button>
+
+                  <div
+                    id={contentId}
+                    role="region"
+                    aria-labelledby={titleId}
+                    className={`overflow-hidden transition-all duration-300 ease-out ${
+                      isOpen ? "max-h-[300px] opacity-100" : "pointer-events-none max-h-0 opacity-0"
+                    }`}
+                  >
+                    <p className="text-ink-2/65 border-ink-2/5 border-t px-5 pt-3.5 pb-5.5 text-xs leading-relaxed sm:px-6 sm:text-sm">
+                      {faq.answer}
+                    </p>
+                  </div>
+                </article>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/apps/portfolio/features/templates/components/TemplateFullSystemSpec.tsx b/apps/portfolio/features/templates/components/TemplateFullSystemSpec.tsx
index d3fbfafe..8b184163 100644
--- a/apps/portfolio/features/templates/components/TemplateFullSystemSpec.tsx
+++ b/apps/portfolio/features/templates/components/TemplateFullSystemSpec.tsx
@@ -3,24 +3,46 @@
 import { useState } from "react";
 
 import type { TemplateDetails } from "../data/template-details";
+import TemplateGuidelines from "./TemplateGuidelines";
 
 type SystemSpecProps = {
   details: TemplateDetails;
+  templateId: string;
 };
 
-const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
+const TemplateFullSystemSpec = ({ details, templateId }: SystemSpecProps) => {
   const { system } = details;
 
-  const [activeTab, setActiveTab] = useState<"blueprint" | "layout" | "components" | "json">(
-    "blueprint",
-  );
+  const [activeTab, setActiveTab] = useState<
+    "blueprint" | "layout" | "components" | "json" | "guidelines"
+  >("blueprint");
 
   if (!system) return null;
 
+  const sanitizedSystem = {
+    overview: {
+      genre: system.overview?.genre,
+      canvas: system.overview?.canvas,
+      anchorHue: system.overview?.anchorHue,
+    },
+    colors: system.colors,
+    typography: {
+      fonts: system.typography?.fonts,
+      hierarchy:
+        system.typography?.hierarchy?.map((h) => ({
+          token: h.token,
+          size: h.size,
+          weight: h.weight,
+        })) || [],
+    },
+    shapes: system.shapes,
+  };
+
   const tabs = [
     { id: "blueprint", label: "Visual Blueprint" },
     { id: "layout", label: "Layout & Shapes" },
     { id: "components", label: "Component Spec" },
+    { id: "guidelines", label: "Guidelines" },
     { id: "json", label: "JSON Spec" },
   ] as const;
 
@@ -131,7 +153,10 @@ const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
 
                 <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
                   <div className="border-ink-2/10 dark:bg-paper-2 rounded-2xl border bg-[#faf9f6] p-4.5">
-                    <div className="border-ink-2/10 mb-3 h-10 rounded-xl border bg-[#39e5a1]" />
+                    <div
+                      className="border-ink-2/10 mb-3 h-10 rounded-xl border"
+                      style={{ backgroundColor: system.colors.brand.accentDark || "#39e5a1" }}
+                    />
                     <h4 className="text-ink-2 text-sm font-bold">Accent (Dark)</h4>
                     <p className="text-ink-2/62 mt-1 font-mono text-[11px]">
                       {system.colors.brand.accentDark}
@@ -139,7 +164,10 @@ const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
                   </div>
 
                   <div className="border-ink-2/10 dark:bg-paper-2 rounded-2xl border bg-[#faf9f6] p-4.5">
-                    <div className="border-ink-2/10 mb-3 h-10 rounded-xl border bg-[#1a8f65]" />
+                    <div
+                      className="border-ink-2/10 mb-3 h-10 rounded-xl border"
+                      style={{ backgroundColor: system.colors.brand.accentLight || "#1a8f65" }}
+                    />
                     <h4 className="text-ink-2 text-sm font-bold">Accent (Light)</h4>
                     <p className="text-ink-2/62 mt-1 font-mono text-[11px]">
                       {system.colors.brand.accentLight}
@@ -147,7 +175,10 @@ const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
                   </div>
 
                   <div className="border-ink-2/10 dark:bg-paper-2 rounded-2xl border bg-[#faf9f6] p-4.5">
-                    <div className="border-ink-2/10 mb-3 h-10 rounded-xl border bg-[#0c100e]" />
+                    <div
+                      className="border-ink-2/10 mb-3 h-10 rounded-xl border"
+                      style={{ backgroundColor: system.colors.surface.paperDark || "#0c100e" }}
+                    />
                     <h4 className="text-ink-2 text-sm font-bold">Obsidian Paper</h4>
                     <p className="text-ink-2/62 mt-1 font-mono text-[11px]">
                       {system.colors.surface.paperDark}
@@ -155,7 +186,10 @@ const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
                   </div>
 
                   <div className="border-ink-2/10 dark:bg-paper-2 rounded-2xl border bg-[#faf9f6] p-4.5">
-                    <div className="border-ink-2/10 mb-3 h-10 rounded-xl border bg-[#fbfcf9]" />
+                    <div
+                      className="border-ink-2/10 mb-3 h-10 rounded-xl border"
+                      style={{ backgroundColor: system.colors.surface.paperLight || "#fbfcf9" }}
+                    />
                     <h4 className="text-ink-2 text-sm font-bold">Chalk Paper</h4>
                     <p className="text-ink-2/62 mt-1 font-mono text-[11px]">
                       {system.colors.surface.paperLight}
@@ -348,7 +382,7 @@ const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
                     <span>Target Class</span>
 
                     <span className="bg-ink-2/5 text-ink-2/80 rounded px-1.5 py-0.5">
-                      .signal-{key}
+                      .{templateId}-{key}
                     </span>
                   </div>
                 </div>
@@ -356,18 +390,29 @@ const TemplateFullSystemSpec = ({ details }: SystemSpecProps) => {
             </div>
           )}
 
+          {activeTab === "guidelines" && (
+            <TemplateGuidelines
+              guidelines={details.guidelines}
+              templateName={details.positioning}
+            />
+          )}
+
           {activeTab === "json" && (
             <div className="border-ink-2/10 animate-fade-in max-h-[500px] overflow-x-auto rounded-3xl border bg-[#0f1412] p-6 font-mono text-xs text-emerald-400 shadow-inner">
               <div className="mb-4 flex items-center justify-between border-b border-white/10 pb-3 text-[11px] text-white/50">
                 <span>programmatic_design_spec.json</span>
                 <button
-                  onClick={() => navigator.clipboard.writeText(JSON.stringify(system, null, 2))}
+                  onClick={() =>
+                    navigator.clipboard.writeText(JSON.stringify(sanitizedSystem, null, 2))
+                  }
                   className="cursor-pointer rounded border border-white/10 bg-white/5 px-2.5 py-1 font-bold text-white transition hover:bg-white/10 active:scale-95"
                 >
                   Copy JSON
                 </button>
               </div>
-              <pre className="leading-5">{JSON.stringify(system, null, 2)}</pre>
+              <pre className="leading-5 break-words whitespace-pre-wrap">
+                {JSON.stringify(sanitizedSystem, null, 2)}
+              </pre>
             </div>
           )}
         </div>
diff --git a/apps/portfolio/features/templates/components/TemplateGuidelines.tsx b/apps/portfolio/features/templates/components/TemplateGuidelines.tsx
new file mode 100644
index 00000000..b901c834
--- /dev/null
+++ b/apps/portfolio/features/templates/components/TemplateGuidelines.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import { CheckCircle, XCircle } from "lucide-react";
+
+type GuidelinesProps = {
+  guidelines?: {
+    do: string[];
+    dont: string[];
+  };
+  templateName: string;
+};
+
+export default function TemplateGuidelines({ guidelines, templateName }: GuidelinesProps) {
+  if (!guidelines) return null;
+
+  return (
+    <article className="animate-fade-in grid gap-8 md:grid-cols-2">
+      <div className="border-ink-2/10 dark:bg-panel rounded-3xl border bg-white p-6 md:p-8">
+        <div className="mb-6 flex items-center gap-2.5">
+          <CheckCircle className="shrink-0 text-emerald-500" size={20} />
+          <h3 className="text-ink-2 text-xl font-bold tracking-tight uppercase">
+            Design Best Practices / Do&apos;s
+          </h3>
+        </div>
+
+        <ul className="space-y-4">
+          {guidelines.do.map((item, idx) => (
+            <li key={idx} className="text-ink-2/72 flex gap-3 text-sm leading-relaxed">
+              <span className="flex size-5.5 shrink-0 items-center justify-center rounded-full bg-emerald-500/10 font-mono text-xs font-bold text-emerald-500">
+                {idx + 1}
+              </span>
+              <span>{item}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      <div className="border-ink-2/10 dark:bg-panel rounded-3xl border bg-white p-6 md:p-8">
+        <div className="mb-6 flex items-center gap-2.5">
+          <XCircle className="shrink-0 text-red-500" size={20} />
+          <h3 className="text-ink-2 text-xl font-bold tracking-tight uppercase">
+            Anti-Patterns to Avoid / Don&apos;ts
+          </h3>
+        </div>
+
+        <ul className="space-y-4">
+          {guidelines.dont.map((item, idx) => (
+            <li key={idx} className="text-ink-2/72 flex gap-3 text-sm leading-relaxed">
+              <span className="flex size-5.5 shrink-0 items-center justify-center rounded-full bg-red-500/10 font-mono text-xs font-bold text-red-500">
+                {idx + 1}
+              </span>
+              <span>{item}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </article>
+  );
+}
diff --git a/apps/portfolio/features/templates/data/template-details.ts b/apps/portfolio/features/templates/data/template-details.ts
index 9a240d68..acedd620 100644
--- a/apps/portfolio/features/templates/data/template-details.ts
+++ b/apps/portfolio/features/templates/data/template-details.ts
@@ -1,5 +1,5 @@
 import type { TemplateId } from "@/templates/catalog/templates";
-import { design as signalDesign } from "@/template-library/signal/design";
+import { templatesRegistry } from "@/template-library/registry";
 
 export interface TemplateSystemOverview {
   genre: string;
@@ -22,14 +22,20 @@ export interface TemplateSystemColors {
   brand: {
     accentDark: string;
     accentLight: string;
-    accentHoverDark: string;
-    accentHoverLight: string;
+    accentHoverDark?: string;
+    accentHoverLight?: string;
+    textDark?: string;
+    textLight?: string;
   };
   surface: {
-    paperDark: string;
-    paperLight: string;
-    cardBgDark: string;
-    cardBgLight: string;
+    paperDark?: string;
+    paperLight?: string;
+    cardBgDark?: string;
+    cardBgLight?: string;
+    bgDark?: string;
+    bgLight?: string;
+    raisedDark?: string;
+    raisedLight?: string;
   };
 }
 
@@ -43,7 +49,7 @@ export interface TemplateSystemTypographyHierarchy {
 export interface TemplateSystemTypography {
   fonts: {
     primary: string;
-    utility: string;
+    utility?: string;
   };
   hierarchy: TemplateSystemTypographyHierarchy[];
 }
@@ -53,6 +59,9 @@ export interface TemplateSystemLayout {
   sectionPadding?: string;
   asymmetricSplit?: string;
   containerLimit?: string;
+  windowMargin?: string;
+  chrome?: string;
+  iconRailWidth?: string;
 }
 
 export interface TemplateSystemShapes {
@@ -60,6 +69,9 @@ export interface TemplateSystemShapes {
   itemRadius?: string;
   buttonRadius?: string;
   badgeRadius?: string;
+  windowRadius?: string;
+  tabRadius?: string;
+  chipRadius?: string;
 }
 
 export interface TemplateSystemBreakpoint {
@@ -101,46 +113,10 @@ export type TemplateDetails = {
   bestFor: string[];
   designNotes: string[];
   system?: TemplateSystemSpec;
+  faqs?: Array<{ question: string; answer: string }>;
+  guidelines?: { do: string[]; dont: string[] };
 };
 
-export const templateDetails: Record<TemplateId, TemplateDetails> = {
-  signal: signalDesign,
-
-  atelier: {
-    positioning:
-      "An editorial portfolio for designers, creative technologists, and independent makers.",
-
-    fonts: "Expressive editorial scale with softer spacing and slower content rhythm.",
-    motion:
-      "Scroll can breathe: reveal writing, case studies, testimonials, and visual details gradually.",
-
-    palette: "Warm canvas tones with VeriWorkly blue used as the brand anchor.",
-
-    layout:
-      "Spacious editorial hero, narrative case-study sections, softer cards, and longer reading rhythm.",
-    componentLanguage:
-      "Editorial panels, large typographic moments, warm spacing, softer dividers, and story-first CTAs.",
-
-    contentModel: [
-      "Personal point of view and creative positioning",
-      "Case studies with process, context, and outcomes",
-      "Testimonials, writing, and visual proof",
-      "A contact section that feels like an invitation",
-    ],
-
-    colorScheme: [
-      { name: "Canvas", value: "#f4eee4", className: "bg-[#f4eee4]" },
-      { name: "Ink", value: "#11110f", className: "bg-ink-2" },
-      { name: "VeriWorkly blue", value: "#2563eb", className: "bg-accent" },
-      { name: "Warm panel", value: "#fffaf1", className: "bg-[#fffaf1]" },
-    ],
-
-    bestFor: ["Designers", "Creative builders", "Independent studios", "Visual storytellers"],
-
-    designNotes: [
-      "Editorial pacing gives profile writing, process, and testimonials more room.",
-      "Larger section breaks make visual work and personal voice feel intentional.",
-      "The template works well when case studies need narrative depth.",
-    ],
-  },
-};
+export const templateDetails: Record<TemplateId, TemplateDetails> = Object.fromEntries(
+  Object.entries(templatesRegistry).map(([id, entry]) => [id, entry.design]),
+) as unknown as Record<TemplateId, TemplateDetails>;
diff --git a/apps/portfolio/lib/portfolio.ts b/apps/portfolio/lib/portfolio.ts
index 6383a0cc..6c6b4b96 100644
--- a/apps/portfolio/lib/portfolio.ts
+++ b/apps/portfolio/lib/portfolio.ts
@@ -1,4 +1,4 @@
-import type { TemplateId } from "@/templates/catalog/templates";
+import { type TemplateId, isTemplateId } from "@/templates/catalog/templates";
 
 export { templates } from "@/templates/catalog/templates";
 export type { TemplateId } from "@/templates/catalog/templates";
@@ -335,7 +335,10 @@ export function parsePortfolioContent(input: unknown, fallback = demoPortfolio):
   const seo = (value.seo ?? {}) as Record<string, unknown>;
   return {
     schemaVersion: 1,
-    templateId: value.templateId === "atelier" ? "atelier" : "signal",
+    templateId:
+      typeof value.templateId === "string" && isTemplateId(value.templateId)
+        ? value.templateId
+        : "signal",
     identity: {
       name: text(identity.name, fallback.identity.name, 120),
       headline: text(identity.headline, fallback.identity.headline, 240),
diff --git a/apps/portfolio/templates/catalog/templates.ts b/apps/portfolio/templates/catalog/templates.ts
index 08965df0..325c5118 100644
--- a/apps/portfolio/templates/catalog/templates.ts
+++ b/apps/portfolio/templates/catalog/templates.ts
@@ -1,6 +1,8 @@
-export const templateIds = ["signal", "atelier"] as const;
+import { type PrivateTemplateId, templatesRegistry } from "@/template-library/registry";
 
-export type TemplateId = (typeof templateIds)[number];
+export type TemplateId = PrivateTemplateId;
+
+export const templateIds = Object.keys(templatesRegistry) as unknown as readonly TemplateId[];
 
 export interface TemplateSummary {
   id: TemplateId;
@@ -12,28 +14,18 @@ export interface TemplateSummary {
   strengths: string[];
 }
 
-export const templates: TemplateSummary[] = [
-  {
-    id: "signal",
-    name: "Signal",
-    note: "A precise, proof-first profile for product engineers.",
-    mood: "Structured / technical",
-    audience: "Engineers and product leaders",
-    strengths: ["Project proof", "Clear timelines", "Technical credibility"],
-    image: "/templates/signal-template-preview.png",
-  },
-
-  {
-    id: "atelier",
-    name: "Atelier",
-    note: "An editorial canvas for designers and independent builders.",
-    mood: "Expressive / editorial",
-    audience: "Designers and creative builders",
-    strengths: ["Visual storytelling", "Editorial rhythm", "Distinctive voice"],
-    image: "/templates/atelier-template-preview.png",
-  },
-];
+export const templates: TemplateSummary[] = Object.entries(templatesRegistry).map(
+  ([id, entry]) => ({
+    id: id as TemplateId,
+    name: entry.name,
+    note: entry.note,
+    mood: entry.mood,
+    audience: entry.audience,
+    strengths: entry.strengths,
+    image: entry.image,
+  }),
+);
 
 export function isTemplateId(value: string): value is TemplateId {
-  return templateIds.includes(value as TemplateId);
+  return value in templatesRegistry;
 }
diff --git a/apps/server/src/polyfills.ts b/apps/server/src/polyfills.ts
index a1944a2e..4f7ae784 100644
--- a/apps/server/src/polyfills.ts
+++ b/apps/server/src/polyfills.ts
@@ -25,11 +25,21 @@ if (typeof globalThis.DOMMatrix === "undefined") {
       }
     }
 
-    multiply() { return this; }
-    translate() { return this; }
-    scale() { return this; }
-    rotate() { return this; }
-    inverse() { return this; }
+    multiply() {
+      return this;
+    }
+    translate() {
+      return this;
+    }
+    scale() {
+      return this;
+    }
+    rotate() {
+      return this;
+    }
+    inverse() {
+      return this;
+    }
     toString() {
       return `matrix(${this.a}, ${this.b}, ${this.c}, ${this.d}, ${this.e}, ${this.f})`;
     }
diff --git a/apps/server/src/services/aiPolicy.ts b/apps/server/src/services/aiPolicy.ts
index 9c417702..0abc7804 100644
--- a/apps/server/src/services/aiPolicy.ts
+++ b/apps/server/src/services/aiPolicy.ts
@@ -8,7 +8,6 @@ import {
 } from "#services/aiPrivateConfig";
 import { AI_ACTION_KEYS, type AiActionKey, type AiMode } from "#services/aiTypes";
 import { ApiError } from "#utils/errors";
-import { logger } from "#utils/logger";
 
 const modePolicySchema = z.object({
   credits: z.number().int().positive(),
@@ -49,14 +48,7 @@ function loadPolicy() {
     return cachedPolicy;
   } catch (error) {
     if (error instanceof ApiError) throw error;
-    logger.error("AI policy parsing failed", error);
-    let details = "";
-    if (error instanceof z.ZodError) {
-      details = ": " + error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join(", ");
-    } else if (error instanceof Error) {
-      details = ": " + error.message;
-    }
-    throw new ApiError(503, `AI generation policy is invalid${details}`);
+    throw new ApiError(503, "AI generation policy is invalid.");
   }
 }
 
diff --git a/apps/server/src/services/atsAiPolicy.ts b/apps/server/src/services/atsAiPolicy.ts
index 38c8f485..2e945b3f 100644
--- a/apps/server/src/services/atsAiPolicy.ts
+++ b/apps/server/src/services/atsAiPolicy.ts
@@ -7,7 +7,6 @@ import {
   resolvePrivateAiModel,
 } from "#services/aiPrivateConfig";
 import { ApiError } from "#utils/errors";
-import { logger } from "#utils/logger";
 
 const modelSchema = z.object({
   model: z.string().min(1),
@@ -54,14 +53,7 @@ function loadAtsAiPolicy() {
       cached = atsPolicySchema.parse(getPrivateAiConfig()).ats;
     } catch (error) {
       if (error instanceof ApiError) throw error;
-      logger.error("AI ATS policy parsing failed", error);
-      let details = "";
-      if (error instanceof z.ZodError) {
-        details = ": " + error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join(", ");
-      } else if (error instanceof Error) {
-        details = ": " + error.message;
-      }
-      throw new ApiError(503, `AI ATS policy is invalid${details}`);
+      throw new ApiError(503, "AI ATS policy is invalid.");
     }
   }
   return cached;
diff --git a/scripts/mock-template-library.mjs b/scripts/mock-template-library.mjs
index 62264f78..0beff163 100644
--- a/scripts/mock-template-library.mjs
+++ b/scripts/mock-template-library.mjs
@@ -80,18 +80,55 @@ fs.writeFileSync(path.join(templateLibPath, "types.ts"), typesContent);
 // Registry
 const registryContent = `import type { ComponentType } from "react";
 import type { PortfolioProject } from "./types";
+import type { TemplateDetails } from "../features/templates/data/template-details";
+
+import { design as signalDesign } from "./signal/design";
+import { design as atelierDesign } from "./atelier/design";
 
 export type TemplateComponent = ComponentType<{ project: PortfolioProject }>;
 
-export const templateLoaders = {
-  atelier: () => import("./atelier/AtelierTemplate"),
-  signal: () => import("./signal/SignalTemplate"),
-} satisfies Record<string, () => Promise<{ default: TemplateComponent }>>;
+export interface TemplateRegistryEntry {
+  name: string;
+  note: string;
+  mood: string;
+  audience: string;
+  strengths: string[];
+  image: string;
+  loader: () => Promise<{ default: TemplateComponent }>;
+  design: TemplateDetails;
+}
+
+export const templatesRegistry = {
+  signal: {
+    name: "Signal",
+    note: "Mock signal note",
+    mood: "Mock signal mood",
+    audience: "Mock signal audience",
+    strengths: ["Mock signal strengths"],
+    image: "/templates/signal-template-preview.png",
+    loader: () => import("./signal/SignalTemplate"),
+    design: signalDesign,
+  },
+  atelier: {
+    name: "Atelier",
+    note: "Mock atelier note",
+    mood: "Mock atelier mood",
+    audience: "Mock atelier audience",
+    strengths: ["Mock atelier strengths"],
+    image: "/templates/atelier-template-preview.png",
+    loader: () => import("./atelier/AtelierTemplate"),
+    design: atelierDesign,
+  },
+} satisfies Record<string, TemplateRegistryEntry>;
+
+export type PrivateTemplateId = keyof typeof templatesRegistry;
 
-export type PrivateTemplateId = keyof typeof templateLoaders;
+export const templateLoaders = Object.fromEntries(
+  Object.entries(templatesRegistry).map(([id, entry]) => [id, entry.loader])
+) as Record<PrivateTemplateId, () => Promise<{ default: TemplateComponent }>>;
 
 export function hasPrivateTemplate(id: string): id is PrivateTemplateId {
-  return id in templateLoaders;
+  return id in templatesRegistry;
 }
 `;
 
@@ -158,6 +195,21 @@ export default function AtelierTemplate({ project }: { project: PortfolioProject
 fs.writeFileSync(path.join(templateLibPath, "atelier", "AtelierTemplate.tsx"), atelierContent);
 fs.writeFileSync(path.join(templateLibPath, "atelier", "styles.css"), "/* Mock styles */");
 
+const atelierDesignContent = `export const design = {
+  positioning: "Mock atelier positioning",
+  fonts: "Mock atelier fonts",
+  motion: "Mock atelier motion",
+  palette: "Mock atelier palette",
+  layout: "Mock atelier layout",
+  componentLanguage: "Mock atelier componentLanguage",
+  contentModel: ["Mock atelier contentModel"],
+  colorScheme: [{ name: "Mock", value: "#000", className: "bg-black" }],
+  bestFor: ["Mock atelier bestFor"],
+  designNotes: ["Mock atelier designNotes"],
+};
+`;
+fs.writeFileSync(path.join(templateLibPath, "atelier", "design.ts"), atelierDesignContent);
+
 // SignalTemplate
 const signalContent = `import React from "react";
 import { safeExternalUrl, itemText, type PortfolioProject } from "../types";