iriai-build 0.1.0

package/v3/artifact-portal.js

@@ -0,0 +1,1184 @@
+// artifact-portal.js — Browsable HTTP portal for all feature planning artifacts.
+// Serves on a single port (default 8900) with feature index, tabbed detail, and individual artifact views.
+// Reuses plan-compiler.js CSS/rendering patterns (Charter fonts, frosted glass, marked.js + mermaid.js).
+
+import { createServer } from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { IMPL_BASE } from "./constants.js";
+import * as queries from "./queries.js";
+
+export class ArtifactPortal {
+  constructor({ reviewSessions } = {}) {
+    this._reviewSessions = reviewSessions;
+    this._server = null;
+  }
+
+  async start(port) {
+    this._server = createServer((req, res) => this._handleRequest(req, res));
+    return new Promise((resolve) => {
+      this._server.listen(port, () => {
+        console.log(`Artifact Portal: http://localhost:${port}`);
+        resolve();
+      });
+    });
+  }
+
+  async stop() {
+    if (!this._server) return;
+    return new Promise((resolve) => {
+      this._server.close(() => resolve());
+    });
+  }
+
+  // ─── Request Router ────────────────────────────────────────────────
+
+  _handleRequest(req, res) {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+
+    try {
+      if (pathname === "/" || pathname === "") {
+        return this._serveIndex(res);
+      }
+
+      if (pathname === "/api/features") {
+        return this._serveApiFeaturesJson(res);
+      }
+
+      const featureMatch = pathname.match(/^\/features\/([^/]+)$/);
+      if (featureMatch) {
+        return this._serveFeatureDetail(res, featureMatch[1]);
+      }
+
+      const rawMatch = pathname.match(/^\/features\/([^/]+)\/raw\/(.+)$/);
+      if (rawMatch) {
+        return this._serveRawFile(res, rawMatch[1], rawMatch[2]);
+      }
+
+      const artifactMatch = pathname.match(/^\/features\/([^/]+)\/plans\/(.+)$/);
+      if (artifactMatch) {
+        return this._serveArtifact(res, artifactMatch[1], artifactMatch[2]);
+      }
+
+      res.writeHead(404, { "Content-Type": "text/html" });
+      res.end(this._render404());
+    } catch (err) {
+      console.error("[artifact-portal] Error:", err.message);
+      res.writeHead(500, { "Content-Type": "text/plain" });
+      res.end("Internal Server Error");
+    }
+  }
+
+  // ─── Route Handlers ────────────────────────────────────────────────
+
+  _serveIndex(res) {
+    const features = this._getAllFeaturesWithArtifacts();
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(this._renderIndex(features));
+  }
+
+  _serveApiFeaturesJson(res) {
+    const features = this._getAllFeaturesWithArtifacts();
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(features, null, 2));
+  }
+
+  _serveFeatureDetail(res, slug) {
+    const feature = queries.getFeatureBySlug(slug);
+    if (!feature) {
+      res.writeHead(404, { "Content-Type": "text/html" });
+      res.end(this._render404());
+      return;
+    }
+
+    const planDir = path.join(IMPL_BASE, "features", slug, "plans");
+    const artifacts = this._scanArtifactTree(planDir);
+    const reviewSessions = this._getReviewSessionsForFeature(feature.id);
+
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(this._renderFeatureDetail(feature, artifacts, reviewSessions));
+  }
+
+  _serveArtifact(res, slug, relativePath) {
+    const resolved = this._resolveAndValidatePath(slug, relativePath);
+    if (!resolved) {
+      res.writeHead(403, { "Content-Type": "text/plain" });
+      res.end("Forbidden: path traversal detected");
+      return;
+    }
+
+    if (!fs.existsSync(resolved)) {
+      res.writeHead(404, { "Content-Type": "text/html" });
+      res.end(this._render404());
+      return;
+    }
+
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end("Cannot view directory");
+      return;
+    }
+
+    const feature = queries.getFeatureBySlug(slug);
+    const content = fs.readFileSync(resolved, "utf-8");
+    const ext = path.extname(resolved).toLowerCase();
+
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(this._renderArtifact(feature, relativePath, content, ext));
+  }
+
+  _serveRawFile(res, slug, relativePath) {
+    const resolved = this._resolveAndValidatePath(slug, relativePath);
+    if (!resolved) {
+      res.writeHead(403, { "Content-Type": "text/plain" });
+      res.end("Forbidden: path traversal detected");
+      return;
+    }
+
+    if (!fs.existsSync(resolved)) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not found");
+      return;
+    }
+
+    const ext = path.extname(resolved).toLowerCase();
+    const mimeTypes = {
+      ".html": "text/html", ".md": "text/markdown", ".yaml": "text/yaml",
+      ".yml": "text/yaml", ".json": "application/json", ".txt": "text/plain",
+    };
+    const contentType = mimeTypes[ext] || "application/octet-stream";
+    const content = fs.readFileSync(resolved);
+
+    res.writeHead(200, {
+      "Content-Type": contentType,
+      "Content-Disposition": `inline; filename="${path.basename(resolved)}"`,
+    });
+    res.end(content);
+  }
+
+  // ─── Data Helpers ──────────────────────────────────────────────────
+
+  _getAllFeaturesWithArtifacts() {
+    const features = queries.getAllFeatures();
+    return features.map(f => {
+      const planDir = path.join(IMPL_BASE, "features", f.slug, "plans");
+      const artifacts = this._scanArtifactTree(planDir);
+      return {
+        ...f,
+        artifactCount: this._countFiles(artifacts),
+        lastArtifactUpdate: this._latestMtime(artifacts),
+      };
+    });
+  }
+
+  _scanArtifactTree(dirPath) {
+    if (!fs.existsSync(dirPath)) return [];
+
+    try {
+      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+      return entries
+        .filter(e => !e.name.startsWith("."))
+        .map(e => {
+          const fullPath = path.join(dirPath, e.name);
+          const stat = fs.statSync(fullPath);
+          if (e.isDirectory()) {
+            return {
+              name: e.name,
+              path: e.name,
+              type: "directory",
+              mtime: stat.mtimeMs,
+              children: this._scanArtifactTree(fullPath).map(child => ({
+                ...child,
+                path: e.name + "/" + child.path,
+              })),
+            };
+          }
+          return {
+            name: e.name,
+            path: e.name,
+            size: stat.size,
+            mtime: stat.mtimeMs,
+            type: path.extname(e.name).slice(1) || "file",
+          };
+        })
+        .sort((a, b) => {
+          if (a.type === "directory" && b.type !== "directory") return -1;
+          if (a.type !== "directory" && b.type === "directory") return 1;
+          return a.name.localeCompare(b.name);
+        });
+    } catch {
+      return [];
+    }
+  }
+
+  _countFiles(artifacts) {
+    let count = 0;
+    for (const a of artifacts) {
+      if (a.type === "directory") count += this._countFiles(a.children || []);
+      else count++;
+    }
+    return count;
+  }
+
+  _latestMtime(artifacts) {
+    let latest = 0;
+    for (const a of artifacts) {
+      if (a.type === "directory") {
+        const sub = this._latestMtime(a.children || []);
+        if (sub > latest) latest = sub;
+      } else if (a.mtime > latest) {
+        latest = a.mtime;
+      }
+    }
+    return latest || null;
+  }
+
+  _flattenArtifacts(artifacts) {
+    const flat = [];
+    for (const a of artifacts) {
+      if (a.type === "directory") {
+        flat.push(...this._flattenArtifacts(a.children || []));
+      } else {
+        flat.push(a);
+      }
+    }
+    return flat;
+  }
+
+  _resolveAndValidatePath(slug, relativePath) {
+    const planDir = path.join(IMPL_BASE, "features", slug, "plans");
+    const resolved = path.resolve(planDir, relativePath);
+    if (!resolved.startsWith(planDir + path.sep) && resolved !== planDir) {
+      return null;
+    }
+    return resolved;
+  }
+
+  _getReviewSessionsForFeature(featureId) {
+    try {
+      return queries.getReviewSessionsByFeature(featureId);
+    } catch {
+      return [];
+    }
+  }
+
+  // ─── Shared CSS ────────────────────────────────────────────────────
+
+  _sharedCss() {
+    return `
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --text-primary: #1a1a2e;
+      --text-secondary: #555;
+      --text-muted: #888;
+      --bg-page: #faf9f7;
+      --bg-header: rgba(250, 249, 247, 0.92);
+      --border-subtle: rgba(0, 0, 0, 0.06);
+      --accent: #2d5be3;
+      --accent-faint: rgba(45, 91, 227, 0.06);
+      --content-width: 720px;
+      --layout-width: 1080px;
+      --gutter: clamp(20px, 5vw, 48px);
+    }
+
+    html {
+      font-size: 18px;
+      -webkit-font-smoothing: antialiased;
+      text-rendering: optimizeLegibility;
+      scroll-behavior: smooth;
+    }
+
+    body {
+      font-family: Charter, Georgia, 'Times New Roman', serif;
+      color: var(--text-primary);
+      background: var(--bg-page);
+      line-height: 1.72;
+      min-height: 100vh;
+    }
+
+    ::selection {
+      background: rgba(45, 91, 227, 0.18);
+      color: inherit;
+    }
+
+    .header {
+      background: var(--bg-header);
+      backdrop-filter: blur(16px);
+      border-bottom: 1px solid var(--border-subtle);
+      padding: 0 var(--gutter);
+      position: sticky;
+      top: 0;
+      z-index: 100;
+    }
+
+    .header-inner {
+      max-width: var(--layout-width);
+      margin: 0 auto;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      height: 56px;
+    }
+
+    .header h1 {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 16px;
+      font-weight: 600;
+      color: var(--text-primary);
+      letter-spacing: -0.01em;
+    }
+
+    .header h1 a {
+      color: inherit;
+      text-decoration: none;
+    }
+
+    .header .badge {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: var(--accent);
+      color: #fff;
+      padding: 3px 10px;
+      border-radius: 12px;
+      font-size: 12px;
+      font-weight: 500;
+    }
+
+    .breadcrumb {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 13px;
+      color: var(--text-muted);
+    }
+
+    .breadcrumb a {
+      color: var(--text-muted);
+      text-decoration: none;
+    }
+
+    .breadcrumb a:hover {
+      color: var(--accent);
+    }
+
+    .breadcrumb .sep {
+      margin: 0 6px;
+      opacity: 0.5;
+    }
+
+    @keyframes fade-up {
+      from { opacity: 0; transform: translateY(12px); }
+      to { opacity: 1; transform: translateY(0); }
+    }`;
+  }
+
+  _markdownCss() {
+    return `
+    .markdown-body {
+      padding: 36px 0 120px;
+      min-width: 0;
+    }
+
+    .markdown-body h1 {
+      font-size: 1.9rem; font-weight: 700; line-height: 1.25;
+      letter-spacing: -0.015em; margin: 2.4em 0 0.6em;
+      padding-bottom: 0.3em; border-bottom: 1px solid var(--border-subtle);
+      color: var(--text-primary);
+    }
+    .markdown-body h1:first-child { margin-top: 0; }
+
+    .markdown-body h2 {
+      font-size: 1.45rem; font-weight: 700; line-height: 1.3;
+      letter-spacing: -0.01em; margin: 2.2em 0 0.5em;
+      padding-bottom: 0.25em; border-bottom: 1px solid var(--border-subtle);
+      color: var(--text-primary);
+    }
+
+    .markdown-body h3 {
+      font-size: 1.15rem; font-weight: 700; line-height: 1.35;
+      margin: 1.8em 0 0.4em; color: var(--text-primary);
+    }
+
+    .markdown-body h4, .markdown-body h5, .markdown-body h6 {
+      font-weight: 700; line-height: 1.4; margin: 1.6em 0 0.4em;
+      color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.04em;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 0.78rem;
+    }
+
+    .markdown-body p { margin-bottom: 1.4em; }
+
+    .markdown-body a { color: var(--accent); text-decoration: underline; text-underline-offset: 2px; text-decoration-thickness: 1px; }
+    .markdown-body a:hover { color: #1a3fa0; }
+
+    .markdown-body strong { font-weight: 700; }
+    .markdown-body em { font-style: italic; }
+
+    .markdown-body blockquote {
+      margin: 1.6em 0; padding: 12px 0 12px 24px;
+      border-left: 3px solid var(--accent); color: var(--text-secondary);
+      font-style: italic; background: var(--accent-faint); border-radius: 0 8px 8px 0;
+    }
+    .markdown-body blockquote p:last-child { margin-bottom: 0; }
+
+    .markdown-body ul, .markdown-body ol { margin: 0 0 1.4em; padding-left: 1.6em; }
+    .markdown-body li { margin-bottom: 0.4em; }
+    .markdown-body li > ul, .markdown-body li > ol { margin-top: 0.4em; margin-bottom: 0; }
+    .markdown-body li::marker { color: var(--text-muted); }
+
+    .markdown-body code {
+      font-family: 'SF Mono', Menlo, Consolas, monospace; font-size: 0.85em;
+      background: var(--accent-faint); padding: 2px 6px; border-radius: 4px;
+      color: #1a3fa0; word-break: break-word;
+    }
+    .markdown-body pre {
+      margin: 1.6em 0; padding: 20px 24px; background: #1a1a2e;
+      border-radius: 10px; overflow-x: auto; line-height: 1.55;
+    }
+    .markdown-body pre code { background: none; padding: 0; color: #c8d0e0; font-size: 0.82rem; }
+
+    .markdown-body hr { border: none; height: 1px; background: var(--border-subtle); margin: 2.4em 0; }
+
+    .markdown-body table {
+      width: 100%; border-collapse: collapse; margin: 1.6em 0;
+      font-size: 0.92rem; border: 1px solid var(--border-subtle); border-radius: 8px; overflow: hidden;
+    }
+    .markdown-body th, .markdown-body td { padding: 10px 14px; text-align: left; border-bottom: 1px solid var(--border-subtle); }
+    .markdown-body th {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-weight: 600; font-size: 0.78rem; text-transform: uppercase;
+      letter-spacing: 0.04em; color: var(--text-muted); background: rgba(0,0,0,0.02);
+    }
+    .markdown-body tr:last-child td { border-bottom: none; }
+    .markdown-body tr:hover td { background: rgba(45, 91, 227, 0.02); }
+
+    .mermaid { background: #1a1a2e; padding: 24px; border-radius: 10px; margin: 1.6em 0; }`;
+  }
+
+  // ─── Page Renderers ────────────────────────────────────────────────
+
+  _renderIndex(features) {
+    const phaseColor = (phase) => {
+      const colors = {
+        planning: "#2d5be3",
+        "plan-approval": "#d97706",
+        impl: "#16a34a",
+        complete: "#059669",
+        failed: "#dc2626",
+      };
+      return colors[phase] || "#888";
+    };
+
+    const cards = features.map(f => {
+      const phase = f.phase || "unknown";
+      const role = f.active_planning_role || "";
+      const count = f.artifactCount || 0;
+      const updated = f.updated_at ? new Date(f.updated_at + "Z").toLocaleDateString("en-US", { month: "short", day: "numeric" }) : "";
+
+      return `
+        <a href="/features/${this._escHtml(f.slug)}" class="card">
+          <div class="card-header">
+            <span class="card-title">${this._escHtml(f.slug)}</span>
+            <span class="phase-badge" style="background: ${phaseColor(phase)}">${this._escHtml(phase)}</span>
+          </div>
+          <div class="card-meta">
+            ${role ? `<span class="meta-item">Role: ${this._escHtml(role)}</span>` : ""}
+            <span class="meta-item">${count} artifact${count !== 1 ? "s" : ""}</span>
+            ${updated ? `<span class="meta-item">Updated ${updated}</span>` : ""}
+          </div>
+        </a>`;
+    }).join("\n");
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Artifact Portal</title>
+  <style>
+    ${this._sharedCss()}
+
+    .grid {
+      max-width: var(--layout-width);
+      margin: 32px auto;
+      padding: 0 var(--gutter);
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
+      gap: 16px;
+      animation: fade-up 0.4s ease both;
+    }
+
+    .card {
+      display: block;
+      background: #fff;
+      border: 1px solid var(--border-subtle);
+      border-radius: 10px;
+      padding: 20px 24px;
+      text-decoration: none;
+      color: inherit;
+      transition: border-color 0.15s, box-shadow 0.15s;
+    }
+
+    .card:hover {
+      border-color: var(--accent);
+      box-shadow: 0 2px 12px rgba(45, 91, 227, 0.08);
+    }
+
+    .card-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      margin-bottom: 10px;
+    }
+
+    .card-title {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 15px;
+      font-weight: 600;
+      color: var(--text-primary);
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    .phase-badge {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      color: #fff;
+      padding: 2px 10px;
+      border-radius: 12px;
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.03em;
+      white-space: nowrap;
+      flex-shrink: 0;
+    }
+
+    .card-meta {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      display: flex;
+      flex-wrap: wrap;
+      gap: 12px;
+      font-size: 12px;
+      color: var(--text-muted);
+    }
+
+    .empty-state {
+      max-width: var(--layout-width);
+      margin: 80px auto;
+      text-align: center;
+      color: var(--text-muted);
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 15px;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-inner">
+      <h1>Artifact Portal</h1>
+      <span class="badge">${features.length} feature${features.length !== 1 ? "s" : ""}</span>
+    </div>
+  </div>
+
+  ${features.length > 0
+    ? `<div class="grid">${cards}</div>`
+    : `<div class="empty-state">No features found in the database.</div>`}
+</body>
+</html>`;
+  }
+
+  _renderFeatureDetail(feature, artifacts, reviewSessions) {
+    const flatArtifacts = this._flattenArtifacts(artifacts);
+    const slug = feature.slug;
+    const planDir = path.join(IMPL_BASE, "features", slug, "plans");
+
+    // Build tabs from known artifact patterns
+    const tabDefs = [
+      { id: "prd", label: "PRD", pattern: "prd" },
+      { id: "design", label: "Design", pattern: "design-decisions" },
+      { id: "architecture", label: "Architecture", pattern: "context" },
+      { id: "plan", label: "Plan.yaml", exact: "plan.yaml" },
+      { id: "journeys", label: "Journeys", dir: "journeys" },
+      { id: "phases", label: "Phases", dir: "phases" },
+    ];
+
+    const tabs = [];
+    const usedFiles = new Set();
+
+    for (const def of tabDefs) {
+      if (def.exact) {
+        const a = flatArtifacts.find(a => a.name === def.exact);
+        if (a) {
+          const content = this._safeReadFile(path.join(planDir, a.path));
+          if (content) {
+            tabs.push({ id: def.id, label: def.label, content, type: a.name.endsWith(".yaml") || a.name.endsWith(".yml") ? "yaml" : "md" });
+            usedFiles.add(a.path);
+          }
+        }
+      } else if (def.dir) {
+        const dirArtifact = artifacts.find(a => a.type === "directory" && a.name === def.dir);
+        if (dirArtifact && dirArtifact.children?.length > 0) {
+          const combined = dirArtifact.children
+            .filter(c => c.type !== "directory")
+            .map(c => {
+              usedFiles.add(c.path);
+              const content = this._safeReadFile(path.join(planDir, c.path));
+              return `## ${c.name}\n\n${content || "_Empty file_"}`;
+            })
+            .join("\n\n---\n\n");
+          if (combined) {
+            tabs.push({ id: def.id, label: def.label, content: combined, type: "md" });
+          }
+        }
+      } else if (def.pattern) {
+        const a = flatArtifacts.find(a => a.name.includes(def.pattern) && a.name.endsWith(".md"));
+        if (a) {
+          const content = this._safeReadFile(path.join(planDir, a.path));
+          if (content) {
+            tabs.push({ id: def.id, label: def.label, content, type: "md" });
+            usedFiles.add(a.path);
+          }
+        }
+      }
+    }
+
+    // Add remaining files as "Other" tab
+    const others = flatArtifacts.filter(a => !usedFiles.has(a.path) && a.name !== "HANDOVER.md");
+    if (others.length > 0) {
+      const combined = others.map(a => {
+        const ext = path.extname(a.name).toLowerCase();
+        if (ext === ".html") {
+          return `## ${a.name}\n\n[View Raw](/features/${slug}/raw/${a.path})`;
+        }
+        const content = this._safeReadFile(path.join(planDir, a.path));
+        if (ext === ".json" || ext === ".yaml" || ext === ".yml") {
+          return `## ${a.name}\n\n\`\`\`${ext.slice(1)}\n${content || ""}\n\`\`\``;
+        }
+        return `## ${a.name}\n\n${content || "_Empty file_"}`;
+      }).join("\n\n---\n\n");
+      tabs.push({ id: "other", label: "Other", content: combined, type: "md" });
+    }
+
+    // Check for mockup.html
+    const mockupFile = flatArtifacts.find(a => a.name === "mockup.html");
+    const hasMockup = !!mockupFile;
+
+    // HANDOVER.md tab
+    const handover = flatArtifacts.find(a => a.name === "HANDOVER.md");
+    if (handover) {
+      const content = this._safeReadFile(path.join(planDir, handover.path));
+      if (content) {
+        tabs.push({ id: "handover", label: "Handover", content, type: "md" });
+      }
+    }
+
+    if (tabs.length === 0) {
+      return this._renderEmptyFeature(feature);
+    }
+
+    const phaseColor = {
+      planning: "#2d5be3", "plan-approval": "#d97706",
+      impl: "#16a34a", complete: "#059669", failed: "#dc2626",
+    };
+
+    const tabButtons = tabs.map((t, i) =>
+      `<button class="tab-btn${i === 0 ? " active" : ""}" onclick="showTab('${t.id}')" id="btn-${t.id}">${this._escHtml(t.label)}</button>`
+    ).join("\n        ");
+
+    const tabPanels = tabs.map((t, i) => {
+      const escapedContent = this._escapeForTemplate(t.content);
+      const wrapType = t.type === "yaml" ? "yaml" : "md";
+      const rawContent = wrapType === "yaml"
+        ? "```yaml\n" + t.content + "\n```"
+        : t.content;
+
+      return `<div class="tab-panel${i === 0 ? " active" : ""}" id="panel-${t.id}" data-type="${wrapType}">
+        <div class="markdown-body">${this._escapeForTemplate(rawContent)}</div>
+        <nav class="tab-toc" id="toc-${t.id}"></nav>
+      </div>`;
+    }).join("\n      ");
+
+    // Review session links
+    const sessionLinks = reviewSessions.map(s =>
+      `<a href="http://localhost:${s.qa_port || s.port}" class="session-link" target="_blank">Review: ${s.doc_path ? path.basename(s.doc_path) : s.decision_id}</a>`
+    ).join("");
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${this._escHtml(slug)} - Artifact Portal</title>
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"><\/script>
+  <style>
+    ${this._sharedCss()}
+    ${this._markdownCss()}
+
+    .status-bar {
+      max-width: var(--layout-width);
+      margin: 0 auto;
+      padding: 16px var(--gutter);
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      flex-wrap: wrap;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 13px;
+      color: var(--text-muted);
+      border-bottom: 1px solid var(--border-subtle);
+    }
+
+    .status-badge {
+      color: #fff;
+      padding: 2px 10px;
+      border-radius: 12px;
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+    }
+
+    .tabs {
+      display: flex;
+      gap: 0;
+      background: var(--bg-header);
+      border-bottom: 1px solid var(--border-subtle);
+      padding: 0 var(--gutter);
+      position: sticky;
+      top: 56px;
+      z-index: 99;
+    }
+
+    .tabs-inner {
+      max-width: var(--layout-width);
+      margin: 0 auto;
+      display: flex;
+      width: 100%;
+      overflow-x: auto;
+    }
+
+    .tab-btn {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: none;
+      border: none;
+      color: var(--text-muted);
+      padding: 12px 20px;
+      font-size: 14px;
+      cursor: pointer;
+      border-bottom: 2px solid transparent;
+      transition: all 0.15s;
+      white-space: nowrap;
+    }
+
+    .tab-btn:hover { color: var(--text-primary); }
+    .tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); font-weight: 600; }
+
+    .tab-panel {
+      display: none;
+      max-width: var(--layout-width);
+      margin: 0 auto;
+      padding: 0 var(--gutter);
+    }
+
+    .tab-panel.active {
+      display: grid;
+      grid-template-columns: var(--content-width) 1fr;
+      gap: 0;
+      animation: fade-up 0.4s ease both;
+    }
+
+    .tab-toc {
+      position: sticky;
+      top: 128px;
+      align-self: start;
+      max-height: calc(100vh - 144px);
+      overflow-y: auto;
+      padding: 36px 0 36px 32px;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      border-left: 1px solid var(--border-subtle);
+    }
+
+    .tab-toc:empty { display: none; }
+
+    .tab-toc .toc-title {
+      font-size: 11px; font-weight: 700; text-transform: uppercase;
+      letter-spacing: 0.08em; color: var(--text-muted); margin-bottom: 12px;
+    }
+
+    .tab-toc ol { list-style: none; padding: 0; margin: 0; }
+    .tab-toc li { margin: 0; }
+
+    .tab-toc a {
+      display: block; padding: 4px 0 4px 12px; font-size: 13px; line-height: 1.4;
+      color: var(--text-muted); text-decoration: none;
+      border-left: 2px solid transparent; margin-left: -1px; transition: color 0.15s;
+    }
+
+    .tab-toc a:hover { color: var(--text-primary); }
+    .tab-toc a.active { color: var(--accent); border-left-color: var(--accent); font-weight: 600; }
+    .tab-toc .toc-h3 { padding-left: 24px; font-size: 12px; }
+
+    .session-link {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      display: inline-block;
+      padding: 4px 12px;
+      background: var(--accent-faint);
+      color: var(--accent);
+      border-radius: 6px;
+      font-size: 12px;
+      text-decoration: none;
+      margin-left: 4px;
+    }
+
+    .session-link:hover { background: rgba(45, 91, 227, 0.12); }
+
+    .mockup-btn {
+      display: inline-block;
+      padding: 4px 12px;
+      background: #059669;
+      color: #fff;
+      border-radius: 6px;
+      font-size: 12px;
+      font-weight: 500;
+      text-decoration: none;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    }
+
+    .mockup-btn:hover { background: #047857; }
+
+    .progress { position: fixed; top: 56px; left: 0; width: 0%; height: 2px; background: var(--accent); z-index: 101; transition: width 0.1s linear; }
+
+    @media (max-width: 960px) {
+      .tab-panel.active { grid-template-columns: 1fr; }
+      .tab-toc { display: none; }
+    }
+
+    @media (max-width: 600px) {
+      html { font-size: 16px; }
+      .header-inner { height: 48px; }
+      .tabs { top: 48px; }
+      .tab-btn { padding: 10px 14px; font-size: 13px; }
+    }
+  </style>
+</head>
+<body>
+  <div class="progress" id="progress"></div>
+
+  <div class="header">
+    <div class="header-inner">
+      <h1><a href="/">Artifact Portal</a></h1>
+      <div class="breadcrumb">
+        <a href="/">Portal</a><span class="sep">/</span><span>${this._escHtml(slug)}</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="status-bar">
+    <span class="status-badge" style="background: ${phaseColor[feature.phase] || "#888"}">${this._escHtml(feature.phase || "unknown")}</span>
+    ${feature.active_planning_role ? `<span>Role: ${this._escHtml(feature.active_planning_role)}</span>` : ""}
+    ${feature.gate_number ? `<span>Gate: ${feature.gate_number}</span>` : ""}
+    ${hasMockup ? `<a href="/features/${this._escHtml(slug)}/raw/mockup.html" class="mockup-btn" target="_blank">View Mockup</a>` : ""}
+    ${sessionLinks}
+  </div>
+
+  <div class="tabs">
+    <div class="tabs-inner">
+      ${tabButtons}
+    </div>
+  </div>
+
+  <div class="content">
+    ${tabPanels}
+  </div>
+
+  <script>
+    mermaid.initialize({ startOnLoad: false, theme: 'dark' });
+
+    function showTab(id) {
+      document.querySelectorAll('.tab-panel').forEach(function(p) { p.classList.remove('active'); });
+      document.querySelectorAll('.tab-btn').forEach(function(b) { b.classList.remove('active'); });
+      document.getElementById('panel-' + id).classList.add('active');
+      document.getElementById('btn-' + id).classList.add('active');
+    }
+
+    document.querySelectorAll('.tab-panel').forEach(function(panel) {
+      var body = panel.querySelector('.markdown-body');
+      var tocEl = panel.querySelector('.tab-toc');
+      if (!body) return;
+
+      var raw = body.textContent;
+      body.innerHTML = marked.parse(raw);
+
+      body.querySelectorAll('pre code.language-mermaid').forEach(function(code) {
+        var pre = code.parentElement;
+        var div = document.createElement('div');
+        div.className = 'mermaid';
+        div.textContent = code.textContent;
+        pre.replaceWith(div);
+      });
+
+      if (!tocEl) return;
+      var headings = body.querySelectorAll('h1, h2, h3');
+      if (headings.length < 3) return;
+
+      var html = '<div class="toc-title">On this page</div><ol>';
+      headings.forEach(function(h, i) {
+        var id = panel.id + '-s' + i;
+        h.setAttribute('id', id);
+        var level = h.tagName.toLowerCase();
+        var cls = level === 'h3' ? ' class="toc-h3"' : '';
+        html += '<li><a href="#' + id + '"' + cls + '>' + h.textContent + '</a></li>';
+      });
+      html += '</ol>';
+      tocEl.innerHTML = html;
+    });
+
+    mermaid.run();
+
+    window.addEventListener('scroll', function() {
+      var h = document.documentElement.scrollHeight - window.innerHeight;
+      document.getElementById('progress').style.width = h > 0 ? ((window.scrollY / h) * 100) + '%' : '0%';
+    }, { passive: true });
+  <\/script>
+</body>
+</html>`;
+  }
+
+  _renderArtifact(feature, relativePath, content, ext) {
+    const slug = feature?.slug || "unknown";
+    const filename = path.basename(relativePath);
+    const isHtml = ext === ".html" || ext === ".htm";
+    const isYaml = ext === ".yaml" || ext === ".yml";
+    const isJson = ext === ".json";
+
+    let bodyContent;
+    if (isHtml) {
+      const encoded = this._escHtml(content);
+      bodyContent = `<div class="iframe-wrapper">
+        <iframe srcdoc="${encoded}" sandbox="allow-scripts allow-same-origin" style="width:100%;height:80vh;border:1px solid var(--border-subtle);border-radius:10px;"></iframe>
+      </div>`;
+    } else if (isYaml || isJson) {
+      const lang = isYaml ? "yaml" : "json";
+      bodyContent = `<div class="markdown-body"><div class="raw-content">\`\`\`${lang}\n${this._escapeForTemplate(content)}\n\`\`\`</div></div>
+      <nav class="doc-toc" id="doc-toc"></nav>`;
+    } else {
+      bodyContent = `<div class="markdown-body"><div class="raw-content">${this._escapeForTemplate(content)}</div></div>
+      <nav class="doc-toc" id="doc-toc"></nav>`;
+    }
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${this._escHtml(filename)} - ${this._escHtml(slug)}</title>
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"><\/script>
+  <style>
+    ${this._sharedCss()}
+    ${this._markdownCss()}
+
+    .doc-layout {
+      max-width: var(--layout-width);
+      margin: 0 auto;
+      padding: 0 var(--gutter);
+      display: grid;
+      grid-template-columns: var(--content-width) 1fr;
+      gap: 0;
+      animation: fade-up 0.4s ease both;
+    }
+
+    .doc-toc {
+      position: sticky;
+      top: 80px;
+      align-self: start;
+      max-height: calc(100vh - 96px);
+      overflow-y: auto;
+      padding: 36px 0 36px 32px;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      border-left: 1px solid var(--border-subtle);
+    }
+
+    .doc-toc:empty { display: none; }
+
+    .doc-toc .toc-title {
+      font-size: 11px; font-weight: 700; text-transform: uppercase;
+      letter-spacing: 0.08em; color: var(--text-muted); margin-bottom: 12px;
+    }
+
+    .doc-toc ol { list-style: none; padding: 0; margin: 0; }
+    .doc-toc li { margin: 0; }
+
+    .doc-toc a {
+      display: block; padding: 4px 0 4px 12px; font-size: 13px; line-height: 1.4;
+      color: var(--text-muted); text-decoration: none;
+      border-left: 2px solid transparent; margin-left: -1px; transition: color 0.15s;
+    }
+
+    .doc-toc a:hover { color: var(--text-primary); }
+    .doc-toc a.active { color: var(--accent); border-left-color: var(--accent); font-weight: 600; }
+    .doc-toc .toc-h3 { padding-left: 24px; font-size: 12px; }
+
+    .iframe-wrapper {
+      max-width: var(--layout-width);
+      margin: 24px auto;
+      padding: 0 var(--gutter);
+    }
+
+    .back-link {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      font-size: 13px;
+      color: var(--accent);
+      text-decoration: none;
+    }
+
+    .back-link:hover { text-decoration: underline; }
+
+    @media (max-width: 960px) {
+      .doc-layout { grid-template-columns: 1fr; }
+      .doc-toc { display: none; }
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-inner">
+      <h1><a href="/">Artifact Portal</a></h1>
+      <div class="breadcrumb">
+        <a href="/">Portal</a><span class="sep">/</span><a href="/features/${this._escHtml(slug)}">${this._escHtml(slug)}</a><span class="sep">/</span><span>${this._escHtml(filename)}</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="${isHtml ? "" : "doc-layout"}">
+    ${bodyContent}
+  </div>
+
+  <script>
+    mermaid.initialize({ startOnLoad: false, theme: 'dark' });
+
+    document.querySelectorAll('.raw-content').forEach(function(el) {
+      var raw = el.textContent;
+      var parent = el.parentElement;
+      parent.innerHTML = marked.parse(raw);
+    });
+
+    // Build TOC for single doc
+    var tocEl = document.getElementById('doc-toc');
+    if (tocEl) {
+      var body = document.querySelector('.markdown-body');
+      if (body) {
+        var headings = body.querySelectorAll('h1, h2, h3');
+        if (headings.length >= 3) {
+          var html = '<div class="toc-title">On this page</div><ol>';
+          headings.forEach(function(h, i) {
+            var id = 'doc-s' + i;
+            h.setAttribute('id', id);
+            var level = h.tagName.toLowerCase();
+            var cls = level === 'h3' ? ' class="toc-h3"' : '';
+            html += '<li><a href="#' + id + '"' + cls + '>' + h.textContent + '</a></li>';
+          });
+          html += '</ol>';
+          tocEl.innerHTML = html;
+        }
+      }
+    }
+
+    // Render mermaid
+    document.querySelectorAll('pre code.language-mermaid').forEach(function(code) {
+      var pre = code.parentElement;
+      var div = document.createElement('div');
+      div.className = 'mermaid';
+      div.textContent = code.textContent;
+      pre.replaceWith(div);
+    });
+
+    mermaid.run();
+  <\/script>
+</body>
+</html>`;
+  }
+
+  _renderEmptyFeature(feature) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${this._escHtml(feature.slug)} - Artifact Portal</title>
+  <style>${this._sharedCss()}
+    .empty { max-width: var(--layout-width); margin: 80px auto; text-align: center;
+      color: var(--text-muted); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; font-size: 15px; }
+    .empty a { color: var(--accent); }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-inner">
+      <h1><a href="/">Artifact Portal</a></h1>
+      <div class="breadcrumb">
+        <a href="/">Portal</a><span class="sep">/</span><span>${this._escHtml(feature.slug)}</span>
+      </div>
+    </div>
+  </div>
+  <div class="empty">
+    <p>No planning artifacts found for <strong>${this._escHtml(feature.slug)}</strong>.</p>
+    <p style="margin-top: 12px;"><a href="/">Back to Portal</a></p>
+  </div>
+</body>
+</html>`;
+  }
+
+  _render404() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Not Found - Artifact Portal</title>
+  <style>${this._sharedCss()}
+    .empty { max-width: var(--layout-width); margin: 80px auto; text-align: center;
+      color: var(--text-muted); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; font-size: 15px; }
+    .empty a { color: var(--accent); }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-inner">
+      <h1><a href="/">Artifact Portal</a></h1>
+    </div>
+  </div>
+  <div class="empty">
+    <p>Page not found.</p>
+    <p style="margin-top: 12px;"><a href="/">Back to Portal</a></p>
+  </div>
+</body>
+</html>`;
+  }
+
+  // ─── Utilities ─────────────────────────────────────────────────────
+
+  _safeReadFile(filePath) {
+    try {
+      return fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  _escHtml(str) {
+    if (!str) return "";
+    return String(str)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;");
+  }
+
+  _escapeForTemplate(content) {
+    if (!content) return "";
+    return content.replace(/<\/script>/gi, "<\\/script>");
+  }
+}