@piagent/platform 1.41.0 → 1.42.0

package/scripts/check-public-wording.mjs

@@ -4,7 +4,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = path.resolve(import.meta.dirname, "..");
-const surfaces = ["README.md", "docs", "docs-site/content", "scripts/build-docs-site.mjs",
+const surfaces = ["README.md", "docs", "docs-site/content", "docs-site/releases.json", "CHANGELOG.md",
+  "scripts/build-docs-site.mjs", "scripts/docs-site-nav.mjs", "scripts/docs-site-releases.mjs",
   "packages/piagent-core/README.md", "packages/piagent-core/prompts", "packages/piagent-core/mcp",
   "packages/piagent-core/extensions", "packages/piagent-core/runtime", "templates/project/AGENTS.md"];
 const sourceNames = ["Codex CLI", "Claude CLI", "Claude Code"];

package/scripts/docs-site-icons.mjs

@@ -0,0 +1,84 @@
+// Line icons for the docs site, drawn on a 24px grid with a 1.75px stroke so
+// they sit at the same weight as 14–15px text. Each page carries one inline
+// sprite of the icons it uses and refers to them with <use>, so an icon costs
+// one <symbol> per page rather than a request or a repeated path.
+
+const ICONS = {
+  home: '<path d="M3 10.5 12 3l9 7.5V20a1 1 0 0 1-1 1h-5v-6H9v6H4a1 1 0 0 1-1-1z"/>',
+  network: '<circle cx="12" cy="5" r="2.5"/><circle cx="5" cy="19" r="2.5"/><circle cx="19" cy="19" r="2.5"/><path d="M12 7.5V12m0 0-5.2 5.2M12 12l5.2 5.2"/>',
+  rocket: '<path d="M5.5 15.5C4 17 3.5 19.5 3.5 20.5c1 0 3.5-.5 5-2"/><path d="M9 15 6.5 12.5C8 8.5 11.5 4.5 20 4c-.5 8.5-4.5 12-8.5 13.5z"/><circle cx="14.5" cy="9.5" r="1.5"/>',
+  monitor: '<rect x="3" y="4" width="18" height="12" rx="2"/><path d="M8 20h8M12 16v4"/>',
+  refresh: '<path d="M20 11A8 8 0 0 0 5.3 6.7M4 3v4h4"/><path d="M4 13a8 8 0 0 0 14.7 4.3M20 21v-4h-4"/>',
+  sparkles: '<path d="M11 3c.6 4.6 2.4 6.4 7 7-4.6.6-6.4 2.4-7 7-.6-4.6-2.4-6.4-7-7 4.6-.6 6.4-2.4 7-7z"/><path d="M19 15v5M16.5 17.5h5"/>',
+  target: '<circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="5"/><circle cx="12" cy="12" r="1"/>',
+  sliders: '<path d="M4 7h9M17 7h3M4 17h3M11 17h9"/><circle cx="15" cy="7" r="2"/><circle cx="9" cy="17" r="2"/>',
+  key: '<circle cx="8" cy="15" r="4"/><path d="m10.9 12.1 8.6-8.6M16.5 6.5l2.5 2.5M14 9l2 2"/>',
+  terminal: '<rect x="3" y="4" width="18" height="16" rx="2.5"/><path d="m7.5 9.5 3 2.5-3 2.5M13 15h4"/>',
+  branch: '<circle cx="6" cy="5.5" r="2"/><circle cx="6" cy="18.5" r="2"/><circle cx="18" cy="7.5" r="2"/><path d="M6 7.5v9M18 9.5c0 4.5-5 4-11 7.5"/>',
+  plug: '<path d="M9 3v4M15 3v4M6 7h12v4a6 6 0 0 1-12 0zM12 17v4"/>',
+  server: '<rect x="3" y="4" width="18" height="7" rx="2"/><rect x="3" y="13" width="18" height="7" rx="2"/><path d="M7 7.5h.01M7 16.5h.01"/>',
+  lock: '<rect x="4" y="11" width="16" height="10" rx="2"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/>',
+  "shield-check": '<path d="M12 3 4.5 6v5.5c0 4.8 3.2 8.2 7.5 9.5 4.3-1.3 7.5-4.7 7.5-9.5V6z"/><path d="m9 12 2.2 2.2L15.5 10"/>',
+  shield: '<path d="M12 3 4.5 6v5.5c0 4.8 3.2 8.2 7.5 9.5 4.3-1.3 7.5-4.7 7.5-9.5V6z"/>',
+  layers: '<path d="m12 3 9 5-9 5-9-5z"/><path d="m3 13 9 5 9-5"/><path d="m3 17.5 9 5 9-5" opacity=".55"/>',
+  cpu: '<rect x="6" y="6" width="12" height="12" rx="2"/><rect x="9.5" y="9.5" width="5" height="5" rx=".8"/><path d="M9 2.5V6M15 2.5V6M9 18v3.5M15 18v3.5M2.5 9H6M2.5 15H6M18 9h3.5M18 15h3.5"/>',
+  chart: '<path d="M4 4v16h16"/><path d="M8.5 16v-5M12.5 16V8M16.5 16v-3"/>',
+  wrench: '<path d="M15 6.5a4.5 4.5 0 0 1-6 6l-5 5L6.5 20l5-5a4.5 4.5 0 0 0 6-6L15 11.5l-2.5-2.5z"/>',
+  users: '<circle cx="9" cy="8" r="3.5"/><path d="M2.5 20a6.5 6.5 0 0 1 13 0"/><path d="M16 4.5a3.5 3.5 0 0 1 0 7M18 14a6 6 0 0 1 3.5 6"/>',
+  search: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>',
+  sun: '<circle cx="12" cy="12" r="4"/><path d="M12 2.5v2M12 19.5v2M4.6 4.6 6 6M18 18l1.4 1.4M2.5 12h2M19.5 12h2M4.6 19.4 6 18M18 6l1.4-1.4"/>',
+  moon: '<path d="M20 14.5A8 8 0 1 1 9.5 4a6.5 6.5 0 0 0 10.5 10.5z"/>',
+  menu: '<path d="M4 7h16M4 12h16M4 17h16"/>',
+  "arrow-right": '<path d="M5 12h14M13 6l6 6-6 6"/>',
+  "arrow-up-right": '<path d="M7 17 17 7M8 7h9v9"/>',
+  copy: '<rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V6a2 2 0 0 1 2-2h9"/>',
+  check: '<path d="m5 12 5 5 9-10"/>',
+  hash: '<path d="M5 9h15M4 15h15M10 3 8 21M16 3l-2 18"/>',
+  book: '<path d="M4 5a2 2 0 0 1 2-2h13v16H6a2 2 0 0 0-2 2z"/><path d="M4 21V5M19 19v2H6"/>',
+  edit: '<path d="M4 20h4L19 9l-4-4L4 16z"/><path d="m13.5 6.5 4 4"/>',
+  eye: '<path d="M2.5 12S6 5 12 5s9.5 7 9.5 7-3.5 7-9.5 7-9.5-7-9.5-7z"/><circle cx="12" cy="12" r="3"/>',
+  message: '<path d="M4 5h16v11H9l-5 4z"/>',
+  play: '<path d="M7 4.5v15l12-7.5z"/>',
+  "check-circle": '<circle cx="12" cy="12" r="9"/><path d="m8.5 12 2.5 2.5 4.5-5"/>',
+  alert: '<path d="M12 3 2.5 20h19z"/><path d="M12 10v4M12 17h.01"/>',
+  diff: '<path d="M6 3v12M3 6h6M15 18h6"/><rect x="13" y="3" width="8" height="8" rx="2" opacity=".55"/><rect x="3" y="13" width="8" height="8" rx="2" opacity=".55"/>',
+  camera: '<path d="M4 8h3l2-3h6l2 3h3v11H4z"/><circle cx="12" cy="13" r="3.5"/>',
+  brain: '<path d="M9 4a3 3 0 0 0-3 3 3 3 0 0 0-2 5 3 3 0 0 0 2 5 3 3 0 0 0 3 3h0a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2z"/><path d="M15 4a3 3 0 0 1 3 3 3 3 0 0 1 2 5 3 3 0 0 1-2 5 3 3 0 0 1-3 3h0a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2z"/>',
+  clock: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>',
+  code: '<path d="m8 7-5 5 5 5M16 7l5 5-5 5M14 4l-4 16"/>',
+  file: '<path d="M6 3h8l5 5v13H6z"/><path d="M14 3v5h5"/>',
+  folder: '<path d="M3 6a1 1 0 0 1 1-1h5l2 2h9a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1z"/>',
+  zap: '<path d="M13 2.5 4.5 13.5H12l-1 8 8.5-11H12z"/>',
+  box: '<path d="m12 3 8 4.5v9L12 21l-8-4.5v-9z"/><path d="m4 7.5 8 4.5 8-4.5M12 12v9"/>',
+  apple: '<path d="M16 3.5c-1 .3-2.4 1.3-2.6 3 1.2.1 2.4-.8 2.6-3zM12 8c-1.5-1-5-1-6 2.5S6.5 19 9 20c1.2.5 2-.4 3-.4s1.8.9 3 .4c1.4-.6 2.5-2.7 3-4.5-2.5-1-2.8-4.6-.5-6-1.2-1.6-3.3-2-4.5-1.5z"/>',
+  windows: '<path d="M3.5 5.5 10.5 4.5v7h-7zM13 4.2 20.5 3v8.5H13zM3.5 13h7v7l-7-1zM13 13h7.5v8.5L13 20.3z"/>',
+  linux: '<rect x="3" y="4" width="18" height="16" rx="2.5"/><path d="M7 15.5h4M7 9l3 2-3 2"/>',
+  github: '<path d="M9 19c-4.5 1.5-4.5-2.5-6.5-3m13 6v-3.5a3 3 0 0 0-.9-2.4c3-.3 6.4-1.5 6.4-6.7a5.2 5.2 0 0 0-1.4-3.6 4.8 4.8 0 0 0-.1-3.6s-1.1-.3-3.7 1.4a12.6 12.6 0 0 0-6.6 0C6.6 1.9 5.5 2.2 5.5 2.2a4.8 4.8 0 0 0-.1 3.6A5.2 5.2 0 0 0 4 9.4c0 5.2 3.4 6.4 6.4 6.7a3 3 0 0 0-.9 2.4V22"/>',
+  x: '<path d="M6 6l12 12M18 6 6 18"/>',
+  globe: '<circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3c2.5 2.5 3.5 5.5 3.5 9s-1 6.5-3.5 9c-2.5-2.5-3.5-5.5-3.5-9s1-6.5 3.5-9z"/>',
+  undo: '<path d="M9 14 4 9l5-5"/><path d="M4 9h10.5a5.5 5.5 0 0 1 0 11H11"/>',
+  list: '<path d="M9 6h11M9 12h11M9 18h11M4.5 6h.01M4.5 12h.01M4.5 18h.01"/>',
+  building: '<rect x="4.5" y="3" width="15" height="18" rx="1.5"/><path d="M9 7h1.5M13.5 7H15M9 11h1.5M13.5 11H15M9 15h1.5M13.5 15H15M10 21v-3h4v3"/>',
+  gauge: '<path d="M4 18a8 8 0 1 1 16 0"/><path d="m12 18 4-5"/>'
+};
+
+/** @param {string} name @returns {string} */
+function icon(name, className = "icon") {
+  if (!ICONS[name]) throw new Error(`unknown docs icon: ${name}`);
+  return `<svg class="${className}" viewBox="0 0 24 24" aria-hidden="true"><use href="#icon-${name}"/></svg>`;
+}
+
+/** The icon names a rendered page refers to through <use>. */
+function iconsUsedIn(html) {
+  return [...new Set([...html.matchAll(/href="#icon-([a-z-]+)"/g)].map((match) => match[1]))].sort();
+}
+
+/** One hidden sprite with exactly the icons the page uses. */
+function iconSprite(names) {
+  const unknown = names.filter((name) => !ICONS[name]);
+  if (unknown.length > 0) throw new Error(`unknown docs icon: ${unknown.join(", ")}`);
+  const symbols = names.map((name) => `<symbol id="icon-${name}" viewBox="0 0 24 24">${ICONS[name]}</symbol>`).join("");
+  return `<svg width="0" height="0" style="position:absolute" aria-hidden="true">${symbols}</svg>`;
+}
+
+export { ICONS, icon, iconSprite, iconsUsedIn };

package/scripts/docs-site-nav.mjs

@@ -0,0 +1,302 @@
+// Page order, titles and leads for the docs site, in both languages.
+//
+// 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. Leads are one or two short
+// sentences: they become the page subtitle, the meta description and the text
+// the search palette matches.
+
+const NAV = [
+  {
+    group: "Bắt đầu",
+    pages: [
+      {
+        slug: "index",
+        href: "/",
+        icon: "home",
+        nav: "Tổng quan",
+        title: "Pi Agent Platform",
+        lead: "Coding agent cho cả team: guard kiểm tra mọi tool call, Harness của team tự chạy check và review, một dashboard cho Terminal và trình duyệt."
+      },
+      {
+        slug: "ecosystem",
+        icon: "network",
+        nav: "Hệ sinh thái",
+        title: "Piagent, Agent Watch và Agent Studio",
+        lead: "Phần nào chạy trên máy bạn, phần nào ở máy chủ công ty, và khi nào dùng model cá nhân hay model của công ty."
+      },
+      {
+        slug: "quickstart",
+        icon: "rocket",
+        nav: "Cài đặt",
+        title: "Cài đặt và chạy lượt đầu tiên",
+        lead: "Hai lệnh để cài. Mở repo, chọn profile và quyền, rồi nói việc bằng lời thường."
+      },
+      {
+        slug: "windows",
+        icon: "windows",
+        nav: "Cài trên Windows",
+        title: "Cài 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: "update",
+        icon: "refresh",
+        nav: "Cập nhật và gỡ",
+        title: "Cập nhật, rollback và gỡ cài đặt",
+        lead: "Một lệnh để lên bản mới, dashboard và Terminal tự báo khi có bản mới. Rollback và gỡ cài đặt đều có bước xem trước."
+      },
+      {
+        slug: "whats-new",
+        icon: "sparkles",
+        nav: "Changelog",
+        title: "Changelog",
+        lead: "Mỗi bản phát hành: thay đổi gì, cần bản nào của Studio hay Agent Watch. Bản mới nhất ở trên cùng."
+      },
+      {
+        slug: "scope",
+        icon: "target",
+        nav: "Phạm vi platform",
+        title: "Platform nhận phần nào về mình",
+        lead: "Agent nào cũng có cơ chế governance riêng. Platform này đóng gói một cách vận hành cụ thể trên Pi để mọi repo dùng lại."
+      }
+    ]
+  },
+  {
+    group: "Sử dụng",
+    pages: [
+      {
+        slug: "profiles",
+        icon: "sliders",
+        nav: "Project profile",
+        title: "Chọn đúng profile cho repo",
+        lead: "Profile quyết định protected path, verify command và capability mà repo được cấp; ghi vào .pi/piagent-profile.json và lock tương ứng."
+      },
+      {
+        slug: "permissions",
+        icon: "key",
+        nav: "Permission modes",
+        title: "Đổi quyền theo task bằng một lệnh",
+        lead: "Permission mode chỉ áp dụng cho session hiện tại. Đổi mode không sửa project profile."
+      },
+      {
+        slug: "commands",
+        icon: "terminal",
+        nav: "Command catalog",
+        title: "Command ngắn, hành vi rõ",
+        lead: "Slash command gói sẵn policy và flow; một inspector cho diff, command, safety và context."
+      },
+      {
+        slug: "workflows",
+        icon: "branch",
+        nav: "Workflows",
+        title: "Làm việc hằng ngày",
+        lead: "Không có launcher workflow: nói việc bằng lời thường. Command xem thêm chỉ quan sát, không mở lượt model."
+      }
+    ]
+  },
+  {
+    group: "MCP",
+    pages: [
+      {
+        slug: "mcp",
+        icon: "plug",
+        nav: "Tổng quan MCP",
+        title: "MCP trong Pi Agent Platform",
+        lead: "Platform cài pi-mcp-adapter để dùng MCP tiết kiệm token, và quản lý server trên bốn lớp cấu hình."
+      },
+      {
+        slug: "mcp-servers",
+        icon: "server",
+        nav: "Quản lý server",
+        title: "Thêm, xem và gỡ MCP server",
+        lead: "piagent-mcp có đủ add, remove, get, list, enable, disable trên cả bốn scope."
+      },
+      {
+        slug: "mcp-auth",
+        icon: "lock",
+        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",
+        icon: "shield-check",
+        nav: "Approval gate",
+        title: "Server đến từ repo phải được duyệt",
+        lead: "Clone một repo lạ không cho tác giả repo đó chạy process trên máy bạn. Quyết định lưu ngoài repo và pin theo digest."
+      }
+    ]
+  },
+  {
+    group: "Vận hành",
+    pages: [
+      {
+        slug: "security",
+        icon: "shield",
+        nav: "Security model",
+        title: "Lớp policy, không phải OS sandbox",
+        lead: "Fail-closed trong bề mặt tool được kiểm soát: lock sai, profile sai hay thiếu quyền thì chặn, không đoán."
+      },
+      {
+        slug: "architecture",
+        icon: "layers",
+        nav: "Kiến trúc",
+        title: "Kiến trúc repo",
+        lead: "Core chỉ giữ policy, prompt, guard, skill và script dùng lại được; business logic ở lại project của nó."
+      },
+      {
+        slug: "context-engine",
+        icon: "cpu",
+        nav: "Context Engine",
+        title: "Ít context hơn, giữ nguyên chất lượng",
+        lead: "Index local, retrieval có xếp hạng, tool nạp theo task, compaction theo ngữ nghĩa và telemetry minh bạch."
+      },
+      {
+        slug: "benchmark",
+        icon: "chart",
+        nav: "Benchmark",
+        title: "Bằng chứng chất lượng và hiệu suất",
+        lead: "So Piagent với codex-cli trên cùng model, cùng thinking: 18 nhóm bài, 108 session chấm tự động."
+      },
+      {
+        slug: "runtime",
+        icon: "wrench",
+        nav: "Runtime tools",
+        title: "Terminal command cho người vận hành",
+        lead: "Command chạy ngoài slash command: setup, doctor, benchmark, capability và MCP."
+      },
+      {
+        slug: "team",
+        icon: "users",
+        nav: "Dùng cho team",
+        title: "Một chuẩn vận hành cho cả team",
+        lead: "Mỗi repo link package, chọn profile phù hợp và giữ tài liệu riêng ở repo của dự án đó."
+      }
+    ]
+  }
+];
+
+const EN_GROUPS = {
+  "Bắt đầu": "Get started",
+  "Sử dụng": "Build",
+  MCP: "MCP",
+  "Vận hành": "Operate"
+};
+
+const EN_PAGE_COPY = {
+  index: {
+    nav: "Overview",
+    title: "Pi Agent Platform",
+    lead: "A coding agent for the whole team: a guard checks every tool call, the team's Harness runs checks and review, one dashboard for Terminal and the browser."
+  },
+  ecosystem: {
+    nav: "Ecosystem",
+    title: "Piagent, Agent Watch and Agent Studio",
+    lead: "What runs on your machine, what runs on the company server, and when to use your own model or the company's."
+  },
+  quickstart: {
+    nav: "Install",
+    title: "Install and run your first turn",
+    lead: "Two commands to install. Open a repository, pick its profile and permissions, then ask in plain language."
+  },
+  windows: {
+    nav: "Windows",
+    title: "Install 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."
+  },
+  update: {
+    nav: "Update & uninstall",
+    title: "Update, roll back and uninstall",
+    lead: "One command moves to a new release, and the dashboard and Terminal tell you when one is out. Rollback and uninstall both preview first."
+  },
+  "whats-new": {
+    nav: "Changelog",
+    title: "Changelog",
+    lead: "Every release: what changed and which Studio or Agent Watch it needs. Newest first."
+  },
+  scope: {
+    nav: "Platform scope",
+    title: "What the platform owns",
+    lead: "Every agent has governance primitives. This platform packages one repeatable operating model on Pi for every repository."
+  },
+  profiles: {
+    nav: "Project profiles",
+    title: "Choose the right profile",
+    lead: "A profile sets protected paths, verification commands and the capabilities a repository is granted."
+  },
+  permissions: {
+    nav: "Permission modes",
+    title: "Change permissions per task",
+    lead: "Permission modes apply to the current session only. Changing one does not modify the project profile."
+  },
+  commands: {
+    nav: "Command catalog",
+    title: "Short commands, predictable behaviour",
+    lead: "Slash commands package policy and flow, with one inspector for diffs, commands, safety and context."
+  },
+  workflows: {
+    nav: "Workflows",
+    title: "Day-to-day work",
+    lead: "No workflow launchers: say what you need in plain language. 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 add, remove, get, list, enable and disable across all four scopes."
+  },
+  "mcp-auth": {
+    nav: "Authentication",
+    title: "Authentication and readiness",
+    lead: "The platform stores no tokens and runs no 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 give its author a process on your machine. Decisions live outside the repository, 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 holds reusable policy and runtime infrastructure; business logic stays in the project that owns it."
+  },
+  "context-engine": {
+    nav: "Context Engine",
+    title: "Less context, same model quality",
+    lead: "Local indexing, ranked retrieval, task-driven tool loading, semantic compaction and transparent telemetry."
+  },
+  benchmark: {
+    nav: "Benchmark",
+    title: "Quality and efficiency evidence",
+    lead: "Piagent against codex-cli on the same model and thinking level: 18 task families, 108 automatically graded sessions."
+  },
+  runtime: {
+    nav: "Runtime tools",
+    title: "Terminal commands for operators",
+    lead: "Commands that run outside Pi: setup, updates, doctor, benchmarks, capabilities and MCP."
+  },
+  team: {
+    nav: "Team usage",
+    title: "One operating standard for the team",
+    lead: "Each repository links the package, selects a fitting profile and keeps project documentation in its own repository."
+  }
+};
+
+const NAV_BY_LOCALE = {
+  vi: NAV,
+  en: NAV.map((section) => ({
+    group: EN_GROUPS[section.group] ?? section.group,
+    pages: section.pages.map((page) => ({ ...page, ...EN_PAGE_COPY[page.slug] }))
+  }))
+};
+
+export { NAV, NAV_BY_LOCALE };

package/scripts/docs-site-releases.mjs

@@ -0,0 +1,227 @@
+import fs from "node:fs";
+
+// Release notes, from one source: docs-site/releases.json. Each entry carries
+// both languages, so the Changelog page in VI and EN, the landing page's
+// "latest" cards and CHANGELOG.md are all drawn from the same facts.
+
+const KINDS = ["breaking", "new", "improved", "fixed", "security"];
+const STATUSES = new Set(["stable", "prerelease", "unpublished"]);
+
+const KIND_LABEL = {
+  vi: { breaking: "Thay đổi lớn", new: "Mới", improved: "Cải thiện", fixed: "Sửa lỗi", security: "Bảo mật" },
+  en: { breaking: "Breaking", new: "New", improved: "Improved", fixed: "Fixed", security: "Security" }
+};
+
+const MARKDOWN_HEADING = {
+  breaking: "Breaking changes",
+  new: "Added",
+  improved: "Improved",
+  fixed: "Fixed",
+  security: "Security"
+};
+
+const COPY = {
+  vi: {
+    requires: "Cần",
+    filterAria: "Lọc theo loại thay đổi",
+    all: "Tất cả",
+    archive: "Các bản trước",
+    archiveLead: "Bản cũ hơn, gom theo tháng. Mở một tháng để xem từng thay đổi.",
+    prerelease: "bản thử",
+    unpublished: "không phát hành",
+    latest: "Mới nhất",
+    month: (year, month) => `Tháng ${month}/${year}`,
+    date: (value) => {
+      const [year, month, day] = value.split("-");
+      return `${day}/${month}/${year}`;
+    },
+    readMore: "Xem chi tiết"
+  },
+  en: {
+    requires: "Requires",
+    filterAria: "Filter by kind of change",
+    all: "All",
+    archive: "Earlier releases",
+    archiveLead: "Older releases, grouped by month. Open a month to see every change.",
+    prerelease: "prerelease",
+    unpublished: "not published",
+    latest: "Latest",
+    month: (year, month) => new Date(Date.UTC(Number(year), Number(month) - 1, 1))
+      .toLocaleDateString("en-US", { month: "long", year: "numeric", timeZone: "UTC" }),
+    date: (value) => new Date(`${value}T00:00:00Z`)
+      .toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" }),
+    readMore: "Read more"
+  }
+};
+
+// The newest releases get a full card; everything older folds into months.
+const DETAILED_COUNT = 24;
+
+/** @param {string} file */
+function readReleases(file) {
+  const releases = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!Array.isArray(releases) || releases.length === 0) throw new Error("docs-site/releases.json must be a non-empty array");
+  const seen = new Set();
+  for (const release of releases) {
+    const where = `releases.json ${release?.version ?? "?"}`;
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/.test(release.version ?? "")) throw new Error(`${where}: bad version`);
+    if (seen.has(release.version)) throw new Error(`${where}: duplicate version`);
+    seen.add(release.version);
+    if (release.date !== null && !/^\d{4}-\d{2}-\d{2}$/.test(release.date ?? "")) throw new Error(`${where}: date must be YYYY-MM-DD or null`);
+    if (!STATUSES.has(release.status)) throw new Error(`${where}: status must be stable, prerelease or unpublished`);
+    for (const field of ["title", "summary"]) {
+      if (!release[field]?.en || !release[field]?.vi) throw new Error(`${where}: ${field} needs en and vi`);
+    }
+    if (!Array.isArray(release.items) || release.items.length === 0) throw new Error(`${where}: items must be a non-empty array`);
+    for (const item of release.items) {
+      if (!KINDS.includes(item.kind) || !item.en || !item.vi) throw new Error(`${where}: every item needs a known kind, en and vi`);
+    }
+    if (release.requires !== null && (!release.requires?.en || !release.requires?.vi)) throw new Error(`${where}: requires needs en and vi, or null`);
+  }
+  return releases;
+}
+
+const anchorFor = (version) => `v${version.replace(/\./g, "-")}`;
+
+/** Text from the JSON, escaped, with `code` spans. */
+function inline(text, escapeHtml) {
+  return escapeHtml(text).replace(/`([^`]+)`/g, "<code>$1</code>");
+}
+
+function sortedItems(items) {
+  return [...items].sort((a, b) => KINDS.indexOf(a.kind) - KINDS.indexOf(b.kind));
+}
+
+function statusNote(release, copy) {
+  if (release.status === "prerelease") return ` <span class="tag">${copy.prerelease}</span>`;
+  if (release.status === "unpublished") return ` <span class="tag">${copy.unpublished}</span>`;
+  return "";
+}
+
+function renderItems(release, locale, escapeHtml) {
+  const labels = KIND_LABEL[locale.code];
+  return sortedItems(release.items)
+    .map((item) => `      <li data-kind="${item.kind}"><span class="kind kind-${item.kind}">${labels[item.kind]}</span><span>${inline(item[locale.code], escapeHtml)}</span></li>`)
+    .join("\n");
+}
+
+function renderRelease(release, index, locale, { escapeHtml }) {
+  const copy = COPY[locale.code];
+  const id = anchorFor(release.version);
+  const date = release.date ? `<time class="release-date" datetime="${release.date}">${copy.date(release.date)}</time>` : "";
+  const requires = release.requires
+    ? `\n    <p class="release-requires"><strong>${copy.requires}:</strong> ${inline(release.requires[locale.code], escapeHtml)}</p>`
+    : "";
+  return `<article class="release${index === 0 ? " latest" : ""}" id="${id}" data-release>
+  <div class="release-meta"><a class="release-version" href="#${id}">v${release.version}</a>${date}</div>
+  <div class="release-body">
+    <h3 data-toc-skip id="${id}-title">${inline(release.title[locale.code], escapeHtml)}${statusNote(release, copy)}</h3>
+    <p>${inline(release.summary[locale.code], escapeHtml)}</p>
+    <ul class="release-items">
+${renderItems(release, locale, escapeHtml)}
+    </ul>${requires}
+  </div>
+</article>`;
+}
+
+function monthKey(release) {
+  return release.date ? release.date.slice(0, 7) : "undated";
+}
+
+function renderArchive(releases, locale, { escapeHtml }) {
+  const copy = COPY[locale.code];
+  const months = new Map();
+  for (const release of releases) {
+    const key = monthKey(release);
+    if (!months.has(key)) months.set(key, []);
+    months.get(key).push(release);
+  }
+  const groups = [...months.entries()].map(([key, group]) => {
+    const [year, month] = key.split("-");
+    const label = key === "undated" ? copy.unpublished : copy.month(year, month);
+    const rows = group.map((release) => {
+      const id = anchorFor(release.version);
+      const date = release.date ? ` <span class="release-date">${copy.date(release.date)}</span>` : "";
+      return `    <div class="archive-row" id="${id}">
+      <div class="archive-head"><a class="release-version" href="#${id}">v${release.version}</a>${date}</div>
+      <div class="archive-body">
+        <p><strong>${inline(release.title[locale.code], escapeHtml)}</strong>${statusNote(release, copy)} — ${inline(release.summary[locale.code], escapeHtml)}</p>
+        <ul class="release-items">
+${renderItems(release, locale, escapeHtml).replace(/^/gm, "  ")}
+        </ul>
+      </div>
+    </div>`;
+    }).join("\n");
+    return `  <details class="release-archive">
+    <summary><span>${label}</span><span class="archive-count">${group.length}</span></summary>
+${rows}
+  </details>`;
+  }).join("\n");
+  return `<section class="section archive">
+  <h2 id="archive">${copy.archive}</h2>
+  <p class="section-lead">${copy.archiveLead}</p>
+${groups}
+</section>`;
+}
+
+/** The body of the Changelog page for one locale. */
+function renderReleaseNotes(releases, locale, helpers) {
+  const copy = COPY[locale.code];
+  const labels = KIND_LABEL[locale.code];
+  const detailed = releases.filter((release) => release.status !== "prerelease").slice(0, DETAILED_COUNT);
+  const detailedSet = new Set(detailed);
+  const older = releases.filter((release) => !detailedSet.has(release));
+  const filters = ["all", "new", "improved", "fixed", "security"]
+    .map((kind, index) => `<button type="button" data-filter-kind="${kind}" aria-pressed="${index === 0}">${kind === "all" ? copy.all : labels[kind]}</button>`)
+    .join("");
+  return `<div class="release-filter" role="toolbar" aria-label="${copy.filterAria}">${filters}</div>
+<section class="section releases" data-releases>
+<h2 id="latest" class="sr-only">${copy.latest}</h2>
+${detailed.map((release, index) => renderRelease(release, index, locale, helpers)).join("\n")}
+</section>
+${renderArchive(older, locale, helpers)}`;
+}
+
+/** Three cards for the landing page. */
+function renderLatestReleases(releases, locale, { escapeHtml, icon, hrefFor }) {
+  const copy = COPY[locale.code];
+  const changelog = hrefFor({ slug: "whats-new" }, locale);
+  return releases.filter((release) => release.status === "stable").slice(0, 3).map((release) => `      <a class="update" href="${changelog}#${anchorFor(release.version)}" data-reveal>
+        <span class="update-meta"><span class="release-version">v${release.version}</span>${release.date ? copy.date(release.date) : ""}</span>
+        <h3>${inline(release.title[locale.code], escapeHtml)}</h3>
+        <p>${inline(release.summary[locale.code], escapeHtml)}</p>
+        <span class="update-more">${copy.readMore} ${icon("arrow-right")}</span>
+      </a>`).join("\n");
+}
+
+/** The pill above the landing headline: the newest stable release. */
+function renderHeroPill(releases, locale, { escapeHtml, icon, hrefFor }) {
+  const latest = releases.find((release) => release.status === "stable");
+  return `<a class="hero-pill" href="${hrefFor({ slug: "whats-new" }, locale)}#${anchorFor(latest.version)}"><b>v${latest.version}</b><span>${inline(latest.title[locale.code], escapeHtml)}</span>${icon("arrow-right")}</a>`;
+}
+
+/** CHANGELOG.md, in English, newest first. */
+function renderChangelogMarkdown(releases) {
+  const lines = [
+    "# Changelog",
+    "",
+    "Every release of Pi Agent Platform (`@piagent/platform`), newest first. Versions follow semantic versioning; prereleases and builds that were tagged but never published are marked.",
+    "",
+    "This file is generated from `docs-site/releases.json` by `node scripts/build-docs-site.mjs`, which also renders the [Changelog page](https://piagent.io.vn/en/whats-new). Edit the JSON, not this file. When publishing a tag, copy the version's block into the GitHub Release.",
+    ""
+  ];
+  for (const release of releases) {
+    const suffix = release.status === "unpublished" ? " (not published)" : "";
+    lines.push(release.date ? `## v${release.version} - ${release.date}${suffix}` : `## v${release.version} - not published`, "");
+    lines.push(`**${release.title.en}.** ${release.summary.en}`, "");
+    for (const kind of KINDS) {
+      const items = release.items.filter((item) => item.kind === kind);
+      if (items.length === 0) continue;
+      lines.push(`### ${MARKDOWN_HEADING[kind]}`, "", ...items.map((item) => `- ${item.en}`), "");
+    }
+    if (release.requires) lines.push(`Requires: ${release.requires.en}.`, "");
+  }
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}
+
+export { readReleases, renderChangelogMarkdown, renderHeroPill, renderLatestReleases, renderReleaseNotes };