@piagent/platform 1.2.16 → 1.2.17

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.17 - 2026-08-03
+
+### Bilingual public documentation
+
+- Added a complete English peer for all 17 public documentation pages under
+  `/en`, while preserving existing Vietnamese URLs at the site root.
+- Added same-topic VI/EN switching, localized navigation and copy feedback,
+  canonical URLs, and `hreflang` metadata without adding a client-side i18n
+  framework or language bundle.
+- Extended build, release-identity, scaffold, link-integrity, and locale-parity
+  gates to cover all 34 generated pages.
+- Fixed the multi-page grid breakpoint that kept desktop sidebar and TOC
+  columns active on mobile, restoring a single-column content layout.
+
 ## v1.2.16 - 2026-08-03
 
 ### Codex default

package/README.md

@@ -293,8 +293,8 @@ This repository intentionally excludes:
 - [Architecture (Tiếng Việt)](docs/vi/architecture.md)
 - [Maintainer guide (English)](docs/en/maintainer-guide.md)
 - [Maintainer guide (Tiếng Việt)](docs/vi/maintainer-guide.md)
-- [Public docs site](https://piagent.io.vn)
-- [Static team docs site](docs-site/index.html) — generated from `docs-site/content/`, preview with `npm run site:preview`
+- [Public docs site (VI/EN)](https://piagent.io.vn)
+- [Static team docs site](docs-site/index.html) — bilingual output generated from `docs-site/content/`, preview with `npm run site:preview`
 - [Changelog](CHANGELOG.md)
 - [Vercel docs site deploy](docs/vercel-docs-site.md)
 - [Operator manual tiếng Việt](docs/operator-manual-vietnamese.md)
@@ -330,7 +330,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.2.16` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.2.17` or a reviewed commit.
 
 Ready for:
 

package/docs/README.md

@@ -20,4 +20,4 @@ Every normative architecture document must be listed in `docs/languages.json`. T
 
 ## Existing operating guides
 
-The public static site is Vietnamese and lives under `docs-site/`. Long-form operator documents keep their existing stable paths until they receive a reviewed language pair. Their language must remain explicit in the title or filename during that migration.
+The public static site is bilingual and lives under `docs-site/`. Existing root URLs remain Vietnamese for compatibility; matching English pages live under `/en/`, and every page links to its language peer. Long-form operator documents keep their existing stable paths until they receive a reviewed language pair. Their language must remain explicit in the title or filename during that migration.

package/docs/command-reference-vietnamese.md

@@ -468,8 +468,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.2.16` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.16` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.17` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.17` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.16` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.17` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.16` |
+| Registry distribution | `npm:@piagent/platform@1.2.17` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.16` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.17` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.16
+pi install git:github.com/Vt-mmm/piagent@v1.2.17
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.16` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.16`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.17` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.17`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -120,7 +120,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.16 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.17 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.16`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.17`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +282,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.16 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.17 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -971,8 +971,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.2.16` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.16` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.17` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.17` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -1083,7 +1083,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 command -v piagent-install
 ```
 

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.2.16 | Rollout guidance |
+| Surface | Status for v1.2.17 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.16` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.17` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.2.16 (helper package version)
-tag: v1.2.16
+currentRelease: v1.2.17 (helper package version)
+tag: v1.2.17
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.16
+pi install git:github.com/Vt-mmm/piagent@v1.2.17
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -22,7 +22,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.16, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.17, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 piagent-install --stable
 cd /path/to/project
 pi
@@ -43,7 +43,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.16
+npm install -g --ignore-scripts @piagent/platform@1.2.17
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs/vercel-docs-site.md

@@ -25,23 +25,25 @@ Site là nhiều trang tĩnh, mỗi topic một trang, sinh ra từ một shell
 
 ```text
 docs-site/
-  content/<slug>.html   # nội dung riêng của từng trang, không có header/sidebar/footer
+  content/<slug>.html   # source tiếng Việt; URL giữ ở /<slug>
+  content/en/<slug>.html # source English; URL ở /en/<slug>
   assets/docs.css       # style dùng chung
   assets/docs.js        # sidebar filter, TOC, active-section, copy button
-  <slug>.html           # output đã generate, được commit
+  <slug>.html           # output VI đã generate, được commit
+  en/<slug>.html        # output EN đã generate, được commit
   vercel.json
 scripts/build-docs-site.mjs
 ```
 
-Sidebar chia theo bốn nhóm — Get started, Build, MCP, Operate. Thứ tự nhóm và thứ tự trang nằm trong hằng `NAV` của `scripts/build-docs-site.mjs`; đó cũng là thứ tự của link prev/next ở cuối mỗi trang. Thêm một trang = thêm `docs-site/content/<slug>.html` + một entry trong `NAV`, rồi build lại.
+Sidebar chia theo bốn nhóm — Get started, Build, MCP, Operate. Thứ tự nhóm và thứ tự trang nằm trong hằng `NAV` của `scripts/build-docs-site.mjs`; metadata English nằm trong `EN_PAGE_COPY`. Đây cũng là thứ tự của link prev/next ở cuối mỗi trang. Thêm một trang = thêm đủ fragment VI/EN, thêm metadata vào `NAV` và `EN_PAGE_COPY`, rồi build lại. Root URL giữ VI để không gãy link cũ; EN dùng prefix `/en`. Mỗi cặp có canonical, `hreflang` và language switch giữ nguyên topic.
 
 ```bash
 npm run site:build
 ```
 
-Output HTML được commit, vì Vercel serve file tĩnh và không có build step. `npm run verify` chạy `build-docs-site.mjs --check`, fail khi output đã commit không còn khớp source — cùng cách `catalog/capabilities.json` đang dùng. Không sửa tay `docs-site/<slug>.html`; sửa fragment trong `content/` hoặc sửa shell trong script.
+Output HTML được commit, vì Vercel serve file tĩnh và không có build step. `npm run verify` chạy `build-docs-site.mjs --check`, fail khi output đã commit không còn khớp source — cùng cách `catalog/capabilities.json` đang dùng. Không sửa tay `docs-site/<slug>.html` hoặc `docs-site/en/<slug>.html`; sửa fragment trong `content/` hoặc sửa shell trong script.
 
-Version badge xuất hiện trên mọi trang, nên `npm run release:identity` kiểm tra tất cả `docs-site/*.html` chứ không riêng `index.html`.
+Version badge xuất hiện trên mọi trang, nên `npm run release:identity` kiểm tra recursive toàn bộ generated VI/EN pages chứ không riêng `index.html`.
 
 ## Production promotion policy
 

package/docs-site/architecture.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="vi">
+<html lang="vi" data-copy-success="Đã lấy" data-copy-fallback="Chọn lệnh">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -7,6 +7,9 @@
     <meta name="description" content="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." />
     <meta name="theme-color" content="#050505" />
     <link rel="canonical" href="https://piagent.io.vn/architecture" />
+    <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/architecture" />
+    <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/architecture" />
+    <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/architecture" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <meta property="og:title" content="Kiến trúc repo · Pi Agent Platform Docs" />
     <meta property="og:description" content="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." />
@@ -27,8 +30,11 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.16 docs · VI</span>
-        <a class="button" href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
+        <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · VI</span>
+        <nav class="language-switch" aria-label="Ngôn ngữ">
+          <a class="language-option current" href="/architecture" hreflang="vi" lang="vi" aria-current="true">VI</a>
+          <a class="language-option" href="/en/architecture" hreflang="en" lang="en">EN</a>
+        </nav>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <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" />
@@ -36,7 +42,7 @@
           GitHub
         </a>
         <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
-        <a class="button" href="/commands">Commands</a>
+        <a class="button top-command-link" href="/commands">Commands</a>
       </div>
     </header>
 
@@ -159,10 +165,10 @@
 
             <footer class="footer">
               <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
-              <div class="footer-links" aria-label="External links">
+              <div class="footer-links" aria-label="Liên kết ngoài">
                 <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
                 <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
-                <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
+                <a href="/en/architecture" hreflang="en">English</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>

package/docs-site/assets/docs.css

@@ -114,6 +114,37 @@ pre {
   gap: 10px;
 }
 
+.language-switch {
+  display: grid;
+  grid-template-columns: repeat(2, 34px);
+  height: 34px;
+  padding: 3px;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.035);
+}
+
+.language-option {
+  display: grid;
+  place-items: center;
+  min-width: 0;
+  border-radius: 3px;
+  color: var(--muted);
+  font-family: "JetBrains Mono", ui-monospace, monospace;
+  font-size: 11px;
+  font-weight: 700;
+}
+
+.language-option:hover,
+.language-option:focus-visible {
+  color: var(--text);
+}
+
+.language-option.current {
+  background: var(--accent);
+  color: #111300;
+}
+
 .pill {
   display: inline-flex;
   align-items: center;
@@ -762,6 +793,10 @@ tr:last-child td {
     display: none;
   }
 
+  .top-command-link {
+    display: none;
+  }
+
   .grid.cols-2,
   .grid.cols-3,
   .split {
@@ -784,6 +819,12 @@ tr:last-child td {
   }
 }
 
+@media (max-width: 520px) {
+  .brand span:last-child {
+    display: none;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   html {
     scroll-behavior: auto;
@@ -1397,7 +1438,7 @@ h3[id] {
   background: var(--panel-strong);
 }
 
-@media (max-width: 1180px) {
+@media (min-width: 1021px) and (max-width: 1180px) {
   .layout.with-toc {
     grid-template-columns: var(--sidebar) minmax(0, 1fr);
   }
@@ -1406,3 +1447,13 @@ h3[id] {
     display: none;
   }
 }
+
+@media (max-width: 1020px) {
+  .layout.with-toc {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .toc {
+    display: none;
+  }
+}

package/docs-site/assets/docs.js

@@ -71,11 +71,13 @@ document.querySelectorAll("[data-clip]").forEach((button) => {
   button.addEventListener("click", async () => {
     const text = button.getAttribute("data-clip") || "";
     const original = button.textContent;
+    const copySuccess = document.documentElement.dataset.copySuccess || "Copied";
+    const copyFallback = document.documentElement.dataset.copyFallback || "Select command";
     try {
       await navigator.clipboard.writeText(text);
-      button.textContent = "Đã lấy";
+      button.textContent = copySuccess;
     } catch {
-      button.textContent = "Chọn lệnh";
+      button.textContent = copyFallback;
     }
     setTimeout(() => {
       button.textContent = original;

package/docs-site/benchmark.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="vi">
+<html lang="vi" data-copy-success="Đã lấy" data-copy-fallback="Chọn lệnh">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -7,6 +7,9 @@
     <meta name="description" content="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." />
     <meta name="theme-color" content="#050505" />
     <link rel="canonical" href="https://piagent.io.vn/benchmark" />
+    <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/benchmark" />
+    <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/benchmark" />
+    <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/benchmark" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <meta property="og:title" content="Bằng chứng chất lượng và hiệu suất · Pi Agent Platform Docs" />
     <meta property="og:description" content="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." />
@@ -27,8 +30,11 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.16 docs · VI</span>
-        <a class="button" href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
+        <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · VI</span>
+        <nav class="language-switch" aria-label="Ngôn ngữ">
+          <a class="language-option current" href="/benchmark" hreflang="vi" lang="vi" aria-current="true">VI</a>
+          <a class="language-option" href="/en/benchmark" hreflang="en" lang="en">EN</a>
+        </nav>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <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" />
@@ -36,7 +42,7 @@
           GitHub
         </a>
         <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
-        <a class="button" href="/commands">Commands</a>
+        <a class="button top-command-link" href="/commands">Commands</a>
       </div>
     </header>
 
@@ -322,10 +328,10 @@
 
             <footer class="footer">
               <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
-              <div class="footer-links" aria-label="External links">
+              <div class="footer-links" aria-label="Liên kết ngoài">
                 <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
                 <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
-                <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
+                <a href="/en/benchmark" hreflang="en">English</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>

package/docs-site/commands.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="vi">
+<html lang="vi" data-copy-success="Đã lấy" data-copy-fallback="Chọn lệnh">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -7,6 +7,9 @@
     <meta name="description" content="Ưu tiên dùng slash command vì mỗi command đã gói sẵn policy và flow. Thành viên không cần nhớ lại quy trình trong prompt." />
     <meta name="theme-color" content="#050505" />
     <link rel="canonical" href="https://piagent.io.vn/commands" />
+    <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/commands" />
+    <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/commands" />
+    <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/commands" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <meta property="og:title" content="Command ngắn, rõ, ít token burn · Pi Agent Platform Docs" />
     <meta property="og:description" content="Ưu tiên dùng slash command vì mỗi command đã gói sẵn policy và flow. Thành viên không cần nhớ lại quy trình trong prompt." />
@@ -27,8 +30,11 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.16 docs · VI</span>
-        <a class="button" href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
+        <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · VI</span>
+        <nav class="language-switch" aria-label="Ngôn ngữ">
+          <a class="language-option current" href="/commands" hreflang="vi" lang="vi" aria-current="true">VI</a>
+          <a class="language-option" href="/en/commands" hreflang="en" lang="en">EN</a>
+        </nav>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <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" />
@@ -36,7 +42,7 @@
           GitHub
         </a>
         <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
-        <a class="button" href="/commands">Commands</a>
+        <a class="button top-command-link" href="/commands">Commands</a>
       </div>
     </header>
 
@@ -192,10 +198,10 @@
 
             <footer class="footer">
               <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
-              <div class="footer-links" aria-label="External links">
+              <div class="footer-links" aria-label="Liên kết ngoài">
                 <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
                 <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
-                <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
+                <a href="/en/commands" hreflang="en">English</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>

package/docs-site/content/en/architecture.html

@@ -0,0 +1,33 @@
+<section class="section">
+  <div class="callout">
+    <strong>Dependency direction is enforced by code.</strong>
+    <p><span class="inline-code">architecture/layers.json</span> is machine-readable policy. <span class="inline-code">npm run architecture:check</span> blocks reverse dependencies and files that exceed their size budget.</p>
+  </div>
+  <div class="grid cols-3">
+    <article class="card"><h3 id="composition">Composition</h3><p><span class="inline-code">piagent-guard.ts</span> owns wiring, registration order, and shared runtime state. Feature algorithms do not belong in this file.</p></article>
+    <article class="card"><h3 id="runtime-adapters">Runtime adapters</h3><p><span class="inline-code">packages/piagent-core/runtime</span> owns Pi hooks, commands, tools, session UI, usage, log compaction, and workflow input routing.</p></article>
+    <article class="card"><h3 id="core-services">Core services</h3><p>Policy, task, context, and state modules return structured decisions. Core services do not import runtime adapters or the Pi composition root.</p></article>
+    <article class="card"><h3 id="integrations">Integrations</h3><p><span class="inline-code">mcp/</span>, <span class="inline-code">capabilities/</span>, and <span class="inline-code">security/</span> have explicit ownership and do not embed task workflow logic.</p></article>
+    <article class="card"><h3 id="entrypoints">Entrypoints</h3><p><span class="inline-code">scripts/</span> parses CLI arguments and calls use cases. Metrics, policy, and state transitions are not duplicated in CLI code.</p></article>
+    <article class="card"><h3 id="product-assets">Product assets</h3><p><span class="inline-code">prompts/</span>, <span class="inline-code">skills/</span>, <span class="inline-code">subagents/</span>, <span class="inline-code">adapters/</span>, <span class="inline-code">packs/</span>, and <span class="inline-code">schemas/</span> are declarative assets.</p></article>
+  </div>
+</section>
+
+<section class="section">
+  <div class="section-head">
+    <p class="eyebrow">Ownership</p>
+    <h2 id="state-ownership">Each state has one source of truth</h2>
+    <p>Project profiles and locks may be committed. Task evidence, telemetry, traces, captures, and session history are local state. Derived indexes carry a policy digest and remain rebuildable.</p>
+  </div>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>State</th><th>Owner</th><th>Location</th><th>Committed</th></tr></thead>
+      <tbody>
+        <tr><td>Project profile and lock</td><td>Project</td><td><span class="inline-code">.pi/piagent-profile*.json</span></td><td>Yes</td></tr>
+        <tr><td>Task, trace, telemetry, capture</td><td>Runtime</td><td><span class="inline-code">.pi/piagent-state/</span></td><td>No</td></tr>
+        <tr><td>Session history</td><td>Pi</td><td>Pi session store</td><td>No</td></tr>
+        <tr><td>Shared instructions</td><td>Project</td><td><span class="inline-code">AGENTS.md</span>, project docs</td><td>Yes</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>