@piagent/platform 1.41.0 → 1.42.1

package/scripts/build-docs-site.mjs

@@ -3,6 +3,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { icon, iconSprite, iconsUsedIn } from "./docs-site-icons.mjs";
+import { NAV, NAV_BY_LOCALE } from "./docs-site-nav.mjs";
+import { readReleases, renderChangelogMarkdown, renderHeroPill, renderLatestReleases, renderReleaseNotes } from "./docs-site-releases.mjs";
+
 // Assembles the docs site: one static page per topic, from a shared shell and a
 // content fragment each.
 //
@@ -12,15 +16,20 @@ import { fileURLToPath } from "node:url";
 // here instead and the output is committed. `--check` fails when the committed
 // output no longer matches its source, the same arrangement the capability
 // catalog already uses.
+//
+// Release notes have one source, docs-site/releases.json. It produces the
+// Changelog page in both languages, the "latest" cards on the landing page and
+// CHANGELOG.md, so the three can never disagree.
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const siteRoot = path.join(repoRoot, "docs-site");
 const contentRoot = path.join(siteRoot, "content");
 
 const SITE = {
-  title: "Pi Agent Platform Docs",
+  title: "Pi Agent Platform",
   origin: "https://piagent.io.vn",
   repo: "https://github.com/Vt-mmm/piagent",
+  npm: "https://www.npmjs.com/package/@piagent/platform",
   facebook: "https://www.facebook.com/vinhtam0544/"
 };
 
@@ -44,262 +53,8 @@ const ANALYTICS_SNIPPET = `    <script>
     <script defer src="/_vercel/insights/script.js"></script>
 `;
 
-// Order here is the order in the sidebar, and it is also the order of the
-// previous/next links at the foot of each page.
-const NAV = [
-  {
-    group: "Get started",
-    pages: [
-      {
-        slug: "index",
-        href: "/",
-        nav: "Overview",
-        title: "Pi Agent Platform",
-        lead: "Coding agent cho cả team: một dashboard cho Terminal và trình duyệt, model cá nhân hoặc của công ty, guard kiểm tra mọi tool call."
-      },
-      {
-        slug: "ecosystem",
-        nav: "Hệ sinh thái",
-        title: "Piagent, Agent Watch và Agent Studio",
-        lead: "Một dashboard, hai cách dùng model: tài khoản của bạn, hoặc model của công ty qua Agent Watch và Agent Studio, với Harness tự kiểm tra từng lượt."
-      },
-      {
-        slug: "quickstart",
-        nav: "Quickstart",
-        title: "Step by step cho thành viên mới",
-        lead: "Hai lệnh để cài, mở repo, chọn profile và quyền, rồi giao việc bằng lời thường; guard kiểm tra từng tool call."
-      },
-      {
-        slug: "windows",
-        nav: "Cài trên Windows",
-        title: "Piagent trên Windows bằng một lệnh",
-        lead: "Một lệnh PowerShell cài WSL2, Ubuntu, Piagent và Agent Watch, nối key công ty và thêm Piagent vào Start menu; chạy lại để cập nhật."
-      },
-      {
-        slug: "whats-new",
-        nav: "Có gì mới",
-        title: "Bản 1.9.0: nói việc bằng lời, Harness của team kiểm tra",
-        lead: "Bỏ task contract và lệnh workflow. Chế độ công ty tự yêu cầu check và review; nút Dừng, lệnh có mạng theo lần duyệt và thẻ duyệt dễ đọc hơn."
-      },
-      {
-        slug: "scope",
-        nav: "Phạm vi platform",
-        title: "Platform này nhận phần nào về mình",
-        lead: "Agent coding CLI nào cũng đã có cơ chế governance riêng. Platform này không thay thế lớp đó — nó đóng gói một cách vận hành cụ thể trên Pi để mọi repo dùng lại."
-      }
-    ]
-  },
-  {
-    group: "Build",
-    pages: [
-      {
-        slug: "profiles",
-        nav: "Project profile",
-        title: "Chọn đúng đường ray cho repo",
-        lead: "Profile ghi vào .pi/piagent-profile.json và lock tương ứng. Nó quyết định protected path, verify command và capability mà project cấp."
-      },
-      {
-        slug: "permissions",
-        nav: "Permission modes",
-        title: "Một command để đổi quyền theo task",
-        lead: "Permission mode là session-local override. Đổi mode không sửa project profile."
-      },
-      {
-        slug: "commands",
-        nav: "Command catalog",
-        title: "Command ngắn, rõ, ít token burn",
-        lead: "Slash command gói sẵn policy và flow; một inspector menu duy nhất cho diff, command, safety và context. Thành viên không cần nhớ nhiều command rời."
-      },
-      {
-        slug: "workflows",
-        nav: "Workflows",
-        title: "Workflow thay đổi thế nào sau update",
-        lead: "Từ bản 1.9.0 không còn launcher workflow: nói việc cần làm bằng lời thường. Các command xem thêm chỉ để quan sát và không bao giờ mở lượt model."
-      }
-    ]
-  },
-  {
-    group: "MCP",
-    pages: [
-      {
-        slug: "mcp",
-        nav: "MCP overview",
-        title: "MCP trong Pi Agent Platform",
-        lead: "Pi core không hard-code MCP. Platform cài pi-mcp-adapter để dùng MCP theo kiểu token-efficient, và thêm một lớp quản lý server lên trên bốn layer config."
-      },
-      {
-        slug: "mcp-servers",
-        nav: "Quản lý server",
-        title: "Thêm, xem và gỡ MCP server",
-        lead: "piagent-mcp có bề mặt lệnh đầy đủ chứ không chỉ seed preset: add, remove, get, list, enable, disable — trên cả bốn scope."
-      },
-      {
-        slug: "mcp-auth",
-        nav: "Auth và readiness",
-        title: "Đăng nhập và trạng thái sẵn sàng",
-        lead: "Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được."
-      },
-      {
-        slug: "mcp-approval",
-        nav: "Approval gate",
-        title: "Server đến từ repo phải được duyệt",
-        lead: "Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest."
-      }
-    ]
-  },
-  {
-    group: "Operate",
-    pages: [
-      {
-        slug: "security",
-        nav: "Security model",
-        title: "Policy enforcement layer, không phải OS sandbox",
-        lead: "Platform ưu tiên fail-closed trong bề mặt tool được kiểm soát: khi lock sai, profile sai hoặc quyền không đủ thì chặn, không đoán."
-      },
-      {
-        slug: "architecture",
-        nav: "Architecture",
-        title: "Kiến trúc repo",
-        lead: "Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được."
-      },
-      {
-        slug: "context-engine",
-        nav: "Context Engine",
-        title: "Ít context hơn, giữ nguyên chất lượng model",
-        lead: "Index local, retrieval có xếp hạng, tool loading theo task, semantic compaction và telemetry minh bạch cho Agent Watch."
-      },
-      {
-        slug: "benchmark",
-        nav: "Benchmark",
-        title: "Bằng chứng chất lượng và hiệu suất",
-        lead: "Production benchmark so sánh Piagent với surface codex-cli trên cùng model, cùng thinking level, 18 nhóm bài và 108 session được chấm tự động."
-      },
-      {
-        slug: "runtime",
-        nav: "Runtime tools",
-        title: "Terminal commands cho operator",
-        lead: "Nhóm command này chạy ngoài slash command, dùng cho setup, doctor, benchmark, capability và MCP."
-      },
-      {
-        slug: "team",
-        nav: "Team usage",
-        title: "Team nên dùng như một chuẩn vận hành",
-        lead: "Mỗi repo chỉ cần link package, chọn profile đúng và giữ tài liệu project-specific ở repo của dự án đó."
-      }
-    ]
-  }
-];
-
-const EN_PAGE_COPY = {
-  index: {
-    nav: "Overview",
-    title: "Pi Agent Platform",
-    lead: "A coding agent for the whole team: one dashboard for Terminal and the browser, personal or company models, and a guard that checks every tool call."
-  },
-  ecosystem: {
-    nav: "Ecosystem",
-    title: "Piagent, Agent Watch and Agent Studio",
-    lead: "One dashboard, two ways to use models: your own account, or the company's models through Agent Watch and Agent Studio, with a Harness that checks every turn."
-  },
-  quickstart: {
-    nav: "Quickstart",
-    title: "Step by step for new team members",
-    lead: "Install with two commands, open a repository, choose its profile and permissions, then ask in plain language; the guard checks every tool call."
-  },
-  windows: {
-    nav: "Windows",
-    title: "Piagent on Windows with one command",
-    lead: "One PowerShell command installs WSL2, Ubuntu, Piagent and Agent Watch, binds the company key and adds Piagent to the Start menu; run it again to update."
-  },
-  "whats-new": {
-    nav: "What’s new",
-    title: "1.9.0: ask in plain language, the team's Harness checks",
-    lead: "The task contract and workflow commands are gone. Company mode asks for checks and a review on its own; Stop, network commands on approval and clearer approval cards."
-  },
-  scope: {
-    nav: "Platform scope",
-    title: "What the platform owns",
-    lead: "General coding agents already provide governance primitives. This platform packages one repeatable operating model for Pi across every repository."
-  },
-  profiles: {
-    nav: "Project profiles",
-    title: "Choose the right operating profile",
-    lead: "A project profile defines protected paths, verification commands, and the capabilities granted to a repository."
-  },
-  permissions: {
-    nav: "Permission modes",
-    title: "Change task permissions with one command",
-    lead: "Permission modes are session-local overrides. Changing a mode does not modify the project profile."
-  },
-  commands: {
-    nav: "Command catalog",
-    title: "Short commands with predictable behavior",
-    lead: "Slash commands package policy and workflow directly, with one inspector menu for diffs, commands, safety, and context instead of many one-off commands."
-  },
-  workflows: {
-    nav: "Workflows",
-    title: "How workflows change after the update",
-    lead: "Since 1.9.0 there are no workflow launchers: say what you need in plain language. The optional inspection commands only observe and never start a model turn."
-  },
-  mcp: {
-    nav: "MCP overview",
-    title: "MCP in Pi Agent Platform",
-    lead: "The platform installs pi-mcp-adapter for token-efficient MCP access and manages servers across four configuration layers."
-  },
-  "mcp-servers": {
-    nav: "Server management",
-    title: "Add, inspect, and remove MCP servers",
-    lead: "piagent-mcp provides deterministic add, remove, get, list, enable, and disable operations across all four scopes."
-  },
-  "mcp-auth": {
-    nav: "Authentication",
-    title: "Authentication and readiness",
-    lead: "The platform does not store tokens or run OAuth. It rejects secrets in configuration and reports which servers are actually ready."
-  },
-  "mcp-approval": {
-    nav: "Approval gate",
-    title: "Repository servers require approval",
-    lead: "Cloning an untrusted repository must not grant its author a process on the operator's machine. Decisions live outside the repository and are pinned by digest."
-  },
-  security: {
-    nav: "Security model",
-    title: "Policy enforcement, not an OS sandbox",
-    lead: "Controlled tool surfaces fail closed when profiles, integrity locks or permissions are invalid."
-  },
-  architecture: {
-    nav: "Architecture",
-    title: "Repository architecture",
-    lead: "Core contains reusable policy and runtime infrastructure, while project-specific business logic stays in the project that owns it."
-  },
-  "context-engine": {
-    nav: "Context Engine",
-    title: "Less context without reducing model quality",
-    lead: "Local indexing, ranked retrieval, task-driven tool loading, semantic compaction, and transparent telemetry for Agent Watch."
-  },
-  benchmark: {
-    nav: "Benchmark",
-    title: "Quality and efficiency evidence",
-    lead: "The production benchmark compares Piagent with codex-cli using the same model, thinking level, 18 task families, and 108 automatically graded sessions."
-  },
-  runtime: {
-    nav: "Runtime tools",
-    title: "Terminal commands for operators",
-    lead: "Use these commands outside Pi for setup, updates, doctor checks, benchmarks, capabilities, and MCP management."
-  },
-  team: {
-    nav: "Team usage",
-    title: "A repeatable team operating standard",
-    lead: "Each repository links the package, selects a fitting profile, and keeps project-specific documentation in the repository that owns it."
-  }
-};
-
-const NAV_BY_LOCALE = {
-  vi: NAV,
-  en: NAV.map((section) => ({
-    group: section.group,
-    pages: section.pages.map((page) => ({ ...page, ...EN_PAGE_COPY[page.slug] }))
-  }))
-};
+// Set before first paint so a reader who chose light never sees a dark flash.
+const THEME_SNIPPET = `<script>try{var t=localStorage.getItem("piagent-docs-theme");if(t==="light"||t==="dark")document.documentElement.dataset.theme=t}catch(e){}</script>`;
 
 const LOCALES = {
   vi: {
@@ -312,19 +67,28 @@ const LOCALES = {
       breadcrumb: "Docs",
       language: "Ngôn ngữ",
       githubAria: "Mở GitHub repository",
-      menu: "Lộ trình",
-      commands: "Commands",
+      menu: "Mở menu tài liệu",
+      docs: "Tài liệu",
+      changelog: "Changelog",
+      benchmark: "Benchmark",
       searchAria: "Tìm trong tài liệu",
-      searchPlaceholder: "Tìm trang",
+      searchPlaceholder: "Tìm trong tài liệu…",
+      searchEmpty: "Không có trang nào khớp.",
+      searchHint: ["↑↓ chọn", "↵ mở", "esc đóng"],
+      themeAria: "Đổi giao diện sáng/tối",
       navAria: "Tài liệu",
       pagerAria: "Trang kế tiếp",
       previous: "Trước",
       next: "Tiếp",
       tocAria: "Mục lục trang",
       tocTitle: "Trên trang này",
+      editPage: "Sửa trang này",
       externalLinks: "Liên kết ngoài",
+      skip: "Tới nội dung",
       copySuccess: "Đã lấy",
-      copyFallback: "Chọn lệnh"
+      copyFallback: "Chọn lệnh",
+      copyLabel: "Sao chép",
+      footer: "Pi Agent Platform · MIT · tài liệu tĩnh, không cookie"
     }
   },
   en: {
@@ -337,19 +101,28 @@ const LOCALES = {
       breadcrumb: "Docs",
       language: "Language",
       githubAria: "Open GitHub repository",
-      menu: "Menu",
-      commands: "Commands",
+      menu: "Open docs menu",
+      docs: "Docs",
+      changelog: "Changelog",
+      benchmark: "Benchmark",
       searchAria: "Search documentation",
-      searchPlaceholder: "Search pages",
+      searchPlaceholder: "Search the docs…",
+      searchEmpty: "No page matches.",
+      searchHint: ["↑↓ select", "↵ open", "esc close"],
+      themeAria: "Switch light/dark theme",
       navAria: "Documentation",
       pagerAria: "Adjacent pages",
       previous: "Previous",
       next: "Next",
       tocAria: "Page contents",
       tocTitle: "On this page",
+      editPage: "Edit this page",
       externalLinks: "External links",
+      skip: "Skip to content",
       copySuccess: "Copied",
-      copyFallback: "Select command"
+      copyFallback: "Select command",
+      copyLabel: "Copy",
+      footer: "Pi Agent Platform · MIT · static docs, no cookies"
     }
   }
 };
@@ -396,6 +169,9 @@ function stripTags(value) {
   return text;
 }
 
+const decodeEntities = (value) => value
+  .replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+
 /** @param {string} currentSlug @param {typeof LOCALES.vi} locale @returns {string} */
 function renderNav(currentSlug, locale) {
   return locale.nav.map((section) => {
@@ -404,7 +180,7 @@ function renderNav(currentSlug, locale) {
         const current = page.slug === currentSlug;
         const classes = current ? "nav-link current" : "nav-link";
         const aria = current ? ' aria-current="page"' : "";
-        return `            <a class="${classes}" href="${hrefFor(page, locale)}"${aria}>${escapeHtml(page.nav)}</a>`;
+        return `            <a class="${classes}" href="${hrefFor(page, locale)}"${aria}>${icon(page.icon)}<span>${escapeHtml(page.nav)}</span></a>`;
       })
       .join("\n");
     return `          <div class="nav-group">\n            <p class="nav-title">${escapeHtml(section.group)}</p>\n${links}\n          </div>`;
@@ -413,27 +189,28 @@ function renderNav(currentSlug, locale) {
 
 /** @param {ReturnType<typeof pagesFor>[number]} page @param {typeof LOCALES.vi} locale @returns {string} */
 function renderBreadcrumb(page, locale) {
-  if (page.slug === "index") return "";
   return [
     '            <nav class="breadcrumb" aria-label="Breadcrumb">',
     `              <a href="${hrefFor({ slug: "index", href: "/" }, locale)}">${locale.ui.breadcrumb}</a>`,
     '              <span aria-hidden="true">/</span>',
     `              <span>${escapeHtml(page.group)}</span>`,
-    '              <span aria-hidden="true">/</span>',
-    `              <span>${escapeHtml(page.nav)}</span>`,
     "            </nav>",
     ""
   ].join("\n");
 }
 
-/** @param {ReturnType<typeof pagesFor>[number]} page @returns {string} */
-function renderPageHead(page) {
-  // The landing page carries its own hero, so it is not given a generated head.
-  if (page.slug === "index") return "";
+/** @param {ReturnType<typeof pagesFor>[number]} page @param {typeof LOCALES.vi} locale @returns {string} */
+function renderPageHead(page, locale) {
+  const source = page.slug === "whats-new"
+    ? "docs-site/releases.json"
+    : `docs-site/content/${locale.prefix ? "en/" : ""}${page.slug}.html`;
   return [
     '            <div class="page-head">',
     `              <h1>${escapeHtml(page.title)}</h1>`,
     `              <p>${page.lead}</p>`,
+    '              <div class="page-meta">',
+    `                <a href="${SITE.repo}/blob/main/${source}" target="_blank" rel="noopener noreferrer">${icon("edit")}${locale.ui.editPage}</a>`,
+    "              </div>",
     "            </div>",
     ""
   ].join("\n");
@@ -448,7 +225,7 @@ function renderPager(index, pages, locale) {
   if (previous) {
     parts.push(
       `              <a class="pager-prev" href="${hrefFor(previous, locale)}">`,
-      `                <span class="pager-label">${locale.ui.previous}</span>`,
+      `                <span class="pager-label">← ${locale.ui.previous}</span>`,
       `                <span class="pager-title">${escapeHtml(previous.nav)}</span>`,
       "              </a>"
     );
@@ -456,7 +233,7 @@ function renderPager(index, pages, locale) {
   if (next) {
     parts.push(
       `              <a class="pager-next" href="${hrefFor(next, locale)}">`,
-      `                <span class="pager-label">${locale.ui.next}</span>`,
+      `                <span class="pager-label">${locale.ui.next} →</span>`,
       `                <span class="pager-title">${escapeHtml(next.nav)}</span>`,
       "              </a>"
     );
@@ -465,6 +242,65 @@ function renderPager(index, pages, locale) {
   return parts.join("\n");
 }
 
+function renderTopbar(page, locale, version, home) {
+  const languageLinks = Object.values(LOCALES).map((candidate) => {
+    const current = candidate.code === locale.code;
+    const classes = current ? "language-option current" : "language-option";
+    const aria = current ? ' aria-current="true"' : "";
+    return `<a class="${classes}" href="${hrefFor(page, candidate)}" hreflang="${candidate.code}" lang="${candidate.code}"${aria}>${candidate.label}</a>`;
+  }).join("");
+  const link = (slug, label) => {
+    const current = page.slug === slug ? ' aria-current="page"' : "";
+    return `<a href="${hrefFor({ slug }, locale)}"${current}>${label}</a>`;
+  };
+  const menu = home ? "" : `\n      <button class="icon-button mobile-menu" type="button" data-menu aria-label="${locale.ui.menu}">${icon("menu")}</button>`;
+  return `    <header class="topbar">${menu}
+      <a class="brand" href="${hrefFor({ slug: "index", href: "/" }, locale)}" aria-label="Pi Agent Platform">
+        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" width="28" height="28" /></span>
+        <span class="brand-name"><b>Piagent</b> <span>Platform</span></span>
+      </a>
+      <a class="version-badge" href="${hrefFor({ slug: "whats-new" }, locale)}" data-docs-version="v${version}" title="v${version} docs · ${locale.label}"><span class="dot"></span>v${version}</a>
+      <nav class="top-nav" aria-label="${locale.ui.navAria}">
+        ${link("quickstart", locale.ui.docs)}
+        ${link("whats-new", locale.ui.changelog)}
+        ${link("benchmark", locale.ui.benchmark)}
+      </nav>
+      <span class="top-spacer"></span>
+      <button class="search-trigger" type="button" data-search aria-label="${locale.ui.searchAria}">${icon("search")}<span>${locale.ui.searchPlaceholder}</span><kbd>⌘K</kbd></button>
+      <div class="top-actions">
+        <nav class="language-switch" aria-label="${locale.ui.language}">${languageLinks}</nav>
+        <button class="icon-button theme-toggle" type="button" data-theme-toggle aria-label="${locale.ui.themeAria}">${icon("moon", "icon icon-moon")}${icon("sun", "icon icon-sun")}</button>
+        <a class="icon-button" href="${SITE.repo}" target="_blank" rel="noopener noreferrer" aria-label="${locale.ui.githubAria}">${icon("github")}</a>
+      </div>
+    </header>
+`;
+}
+
+function renderPalette(locale) {
+  const hints = locale.ui.searchHint.map((hint) => `<span>${hint}</span>`).join("");
+  return `    <div class="palette" data-palette data-index="/assets/search-${locale.code}.json" data-empty="${locale.ui.searchEmpty}" role="dialog" aria-modal="true" aria-label="${locale.ui.searchAria}">
+      <div class="palette-box">
+        <label class="palette-input">${icon("search")}<input type="search" placeholder="${locale.ui.searchPlaceholder}" aria-label="${locale.ui.searchAria}" autocomplete="off" spellcheck="false" /></label>
+        <div class="palette-results" data-results role="listbox"></div>
+        <div class="palette-foot">${hints}</div>
+      </div>
+    </div>
+`;
+}
+
+function renderFooter(page, locale) {
+  const other = locale.code === "vi" ? LOCALES.en : LOCALES.vi;
+  return `<footer class="footer">
+              <p>${locale.ui.footer}</p>
+              <div class="footer-links" aria-label="${locale.ui.externalLinks}">
+                <a href="${SITE.repo}" target="_blank" rel="noopener noreferrer">GitHub</a>
+                <a href="${SITE.npm}" target="_blank" rel="noopener noreferrer">npm</a>
+                <a href="${hrefFor(page, other)}" hreflang="${other.code}">${other.code === "en" ? "English" : "Tiếng Việt"}</a>
+                <a href="${SITE.facebook}" target="_blank" rel="noopener noreferrer">Facebook</a>
+              </div>
+            </footer>`;
+}
+
 /**
  * @param {ReturnType<typeof pagesFor>[number]} page
  * @param {number} index
@@ -475,101 +311,91 @@ function renderPager(index, pages, locale) {
  * @returns {string}
  */
 function renderPage(page, index, body, version, locale, pages) {
+  const home = page.slug === "index";
   const canonical = `${SITE.origin}${hrefFor(page, locale)}`;
   const alternateVi = `${SITE.origin}${hrefFor(page, LOCALES.vi)}`;
   const alternateEn = `${SITE.origin}${hrefFor(page, LOCALES.en)}`;
-  const documentTitle = page.slug === "index" ? SITE.title : `${page.title} · ${SITE.title}`;
+  const documentTitle = home ? `${SITE.title} — ${stripTags(page.lead).split(":")[0]}` : `${page.title} · ${SITE.title}`;
   const description = stripTags(page.lead);
-  const languageLinks = Object.values(LOCALES).map((candidate) => {
-    const current = candidate.code === locale.code;
-    const classes = current ? "language-option current" : "language-option";
-    const aria = current ? ' aria-current="true"' : "";
-    return `<a class="${classes}" href="${hrefFor(page, candidate)}" hreflang="${candidate.code}" lang="${candidate.code}"${aria}>${candidate.label}</a>`;
-  }).join("\n          ");
+
+  const main = home
+    ? `    <main id="content" class="home-main" data-article>
+${body}
+    </main>
+    <footer class="site-footer">
+      <div class="home-wrap">
+        <p>${locale.ui.footer}</p>
+        <nav aria-label="${locale.ui.externalLinks}">
+          <a href="${hrefFor({ slug: "quickstart" }, locale)}">${locale.ui.docs}</a>
+          <a href="${hrefFor({ slug: "whats-new" }, locale)}">${locale.ui.changelog}</a>
+          <a href="${SITE.repo}" target="_blank" rel="noopener noreferrer">GitHub</a>
+          <a href="${SITE.npm}" target="_blank" rel="noopener noreferrer">npm</a>
+          <a href="${hrefFor(page, locale.code === "vi" ? LOCALES.en : LOCALES.vi)}" hreflang="${locale.code === "vi" ? "en" : "vi"}">${locale.code === "vi" ? "English" : "Tiếng Việt"}</a>
+        </nav>
+      </div>
+    </footer>
+`
+    : `    <div class="layout with-toc">
+      <aside class="sidebar" data-sidebar>
+        <nav aria-label="${locale.ui.navAria}">
+${renderNav(page.slug, locale)}
+        </nav>
+      </aside>
+
+      <main id="content">
+        <div class="content-shell" data-article>
+${renderBreadcrumb(page, locale)}${renderPageHead(page, locale)}${body}
+${renderPager(index, pages, locale)}
+            ${renderFooter(page, locale)}
+        </div>
+      </main>
+
+      <aside class="toc" aria-label="${locale.ui.tocAria}">
+        <p class="toc-title">${locale.ui.tocTitle}</p>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+`;
+
+  const shell = `${renderTopbar(page, locale, version, home)}
+${main}${renderPalette(locale)}`;
+  const navIcons = pagesFor(locale).map((candidate) => candidate.icon);
+  const sprite = iconSprite([...new Set([...iconsUsedIn(shell), ...navIcons, "hash"])].sort());
 
   return `<!doctype html>
-<html lang="${locale.code}" data-copy-success="${locale.ui.copySuccess}" data-copy-fallback="${locale.ui.copyFallback}">
+<html lang="${locale.code}" data-copy-success="${locale.ui.copySuccess}" data-copy-fallback="${locale.ui.copyFallback}" data-copy-label="${locale.ui.copyLabel}">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>${escapeHtml(documentTitle)}</title>
     <meta name="description" content="${escapeHtml(description)}" />
-    <meta name="theme-color" content="#050505" />
+    <meta name="theme-color" content="#09090b" media="(prefers-color-scheme: dark)" />
+    <meta name="theme-color" content="#fbfbf9" media="(prefers-color-scheme: light)" />
     <link rel="canonical" href="${canonical}" />
     <link rel="alternate" hreflang="vi" href="${alternateVi}" />
     <link rel="alternate" hreflang="en" href="${alternateEn}" />
     <link rel="alternate" hreflang="x-default" href="${alternateVi}" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <meta property="og:type" content="website" />
     <meta property="og:title" content="${escapeHtml(documentTitle)}" />
     <meta property="og:description" content="${escapeHtml(description)}" />
     <meta property="og:url" content="${canonical}" />
+    <meta property="og:image" content="${SITE.origin}/assets/og.png" />
+    <meta name="twitter:card" content="summary_large_image" />
+    ${THEME_SNIPPET}
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link
-      href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;450;500;550;600;650;700;750&family=JetBrains+Mono:wght@400;500;600;700&display=swap"
       rel="stylesheet"
     />
     <link rel="stylesheet" href="/assets/docs.css" />
     <script src="/assets/docs.js" defer></script>
   </head>
-  <body>
-    <header class="topbar">
-      <a class="brand" href="${hrefFor({ slug: "index", href: "/" }, locale)}" aria-label="Pi Agent Platform">
-        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
-        <span>Pi Agent Platform</span>
-      </a>
-      <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v${version} docs · ${locale.label}</span>
-        <nav class="language-switch" aria-label="${locale.ui.language}">
-          ${languageLinks}
-        </nav>
-        <a class="button social" href="${SITE.repo}" target="_blank" rel="noopener noreferrer" aria-label="${locale.ui.githubAria}">
-          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
-            <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
-          </svg>
-          GitHub
-        </a>
-        <button class="button mobile-menu" type="button" data-menu>${locale.ui.menu}</button>
-        <a class="button top-command-link" href="${hrefFor({ slug: "commands" }, locale)}">${locale.ui.commands}</a>
-      </div>
-    </header>
-
-    <div class="layout with-toc">
-      <aside class="sidebar" data-sidebar>
-        <div class="sidebar-search" aria-label="${locale.ui.searchAria}">
-          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
-            <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
-          </svg>
-          <input type="search" placeholder="${locale.ui.searchPlaceholder}" data-filter />
-        </div>
-
-        <nav aria-label="${locale.ui.navAria}">
-${renderNav(page.slug, locale)}
-        </nav>
-      </aside>
-
-      <main>
-        <div class="content-shell" data-article>
-${renderBreadcrumb(page, locale)}${renderPageHead(page)}${body}
-${renderPager(index, pages, locale)}
-            <footer class="footer">
-              <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
-              <div class="footer-links" aria-label="${locale.ui.externalLinks}">
-                <a href="${SITE.origin}" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
-                <a href="${SITE.repo}" target="_blank" rel="noopener noreferrer">GitHub repository</a>
-                <a href="${hrefFor(page, locale.code === "vi" ? LOCALES.en : LOCALES.vi)}" hreflang="${locale.code === "vi" ? "en" : "vi"}">${locale.code === "vi" ? "English" : "Tiếng Việt"}</a>
-                <a href="${SITE.facebook}" target="_blank" rel="noopener noreferrer">Facebook profile</a>
-              </div>
-            </footer>
-        </div>
-      </main>
-
-      <aside class="toc" aria-label="${locale.ui.tocAria}">
-        <p class="toc-title">${locale.ui.tocTitle}</p>
-        <nav data-toc></nav>
-      </aside>
-    </div>
-${ANALYTICS_SNIPPET}  </body>
+  <body${home ? ' class="home"' : ""}>
+    ${sprite}
+    <a class="skip-link" href="#content">${locale.ui.skip}</a>
+${shell}${ANALYTICS_SNIPPET}  </body>
 </html>
 `;
 }
@@ -602,23 +428,54 @@ function assertPreBlocksIntact(slug, body, html) {
   }
 }
 
+/** Page and heading entries the search palette loads on first use. */
+function searchEntry(page, body, locale) {
+  const headings = [...body.matchAll(/<h([23])\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/h\1>/g)]
+    .map(([, , id, text]) => ({ id, text: decodeEntities(stripTags(text)).replace(/\s+/g, " ").trim() }))
+    .filter((heading) => heading.text);
+  return {
+    href: hrefFor(page, locale),
+    icon: page.icon,
+    group: page.group,
+    nav: page.nav,
+    title: page.title,
+    lead: decodeEntities(stripTags(page.lead)),
+    headings
+  };
+}
+
 function build() {
-  const version = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
+  const rootPackage = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+  const version = rootPackage.version;
+  const piHost = rootPackage.peerDependencies["@earendil-works/pi-coding-agent"];
+  const releases = readReleases(path.join(siteRoot, "releases.json"));
   /** @type {{file: string, html: string}[]} */
   const outputs = [];
   for (const locale of Object.values(LOCALES)) {
     const pages = pagesFor(locale);
-    for (const [index, page] of pages.entries()) {
+    const index = [];
+    for (const [position, page] of pages.entries()) {
       const fragment = path.join(locale.contentRoot, `${page.slug}.html`);
       if (!fs.existsSync(fragment)) throw new Error(`missing content fragment: ${path.relative(repoRoot, fragment)}`);
-      const body = fs.readFileSync(fragment, "utf8").replace(/\s+$/, "");
+      let body = fs.readFileSync(fragment, "utf8").replace(/\s+$/, "");
       if (body.includes("\t")) throw new Error(`${locale.code}/${page.slug}: content fragment contains a tab character`);
-      const html = renderPage(page, index, body, version, locale, pages);
+      body = body
+        .replace("<!-- releases -->", () => renderReleaseNotes(releases, locale, { escapeHtml, icon }))
+        .replace("<!-- latest-releases -->", () => renderLatestReleases(releases, locale, { escapeHtml, icon, hrefFor }))
+        .replace("<!-- hero-pill -->", () => renderHeroPill(releases, locale, { escapeHtml, icon, hrefFor }))
+        .replaceAll("{{version}}", version)
+        .replaceAll("{{piHost}}", piHost)
+        .replaceAll("{{releaseCount}}", String(releases.filter((release) => release.status === "stable").length))
+        .replace(/\{\{icon:([a-z-]+)\}\}/g, (_, name) => icon(name));
+      const html = renderPage(page, position, body, version, locale, pages);
       assertPreBlocksIntact(`${locale.code}/${page.slug}`, body, html);
       const outputDir = locale.prefix ? path.join(siteRoot, locale.code) : siteRoot;
       outputs.push({ file: path.join(outputDir, `${page.slug}.html`), html });
+      index.push(searchEntry(page, body, locale));
     }
+    outputs.push({ file: path.join(siteRoot, "assets", `search-${locale.code}.json`), html: `${JSON.stringify(index)}\n` });
   }
+  outputs.push({ file: path.join(repoRoot, "CHANGELOG.md"), html: renderChangelogMarkdown(releases) });
   return outputs;
 }
 
@@ -639,7 +496,7 @@ function main(argv) {
     });
     if (stale.length > 0) {
       process.stderr.write(
-        `FAIL: docs-site output is stale for ${stale.map((item) => path.relative(siteRoot, item.file)).join(", ")}. ` +
+        `FAIL: docs-site output is stale for ${stale.map((item) => path.relative(repoRoot, item.file)).join(", ")}. ` +
         "Run: node scripts/build-docs-site.mjs\n"
       );
       return 1;