@piagent/platform 1.2.16 → 1.3.0-ie.8

package/docs-site/content/en/whats-new.html

@@ -0,0 +1,107 @@
+<section class="section">
+  <p class="section-kicker">Product stabilization</p>
+  <h2 id="main-changes">Six changes users will notice</h2>
+  <p class="section-lead">Existing workflows continue to work. This update adds runtime evidence and fail-closed gates behind them, plus compact projections that users can inspect when needed.</p>
+  <div class="grid cols-3">
+    <article class="card">
+      <h3 id="runtime-truth">Runtime truth</h3>
+      <p>Model, provider, thinking, context window, and provenance come from the runtime or authenticated catalog. Missing facts stay unknown instead of being inferred from a model name.</p>
+    </article>
+    <article class="card">
+      <h3 id="trajectory">Task trajectories</h3>
+      <p>Tasks move through plan, execute, verify, review, handoff, and terminal using replayable state. Stale, corrupt, or identity-mismatched events fail closed.</p>
+    </article>
+    <article class="card">
+      <h3 id="recovery">Recovery and resume</h3>
+      <p>Failures are classified before retry or repair. Environment, provider, permission, policy, and scope failures never grant source-mutation authority.</p>
+    </article>
+    <article class="card">
+      <h3 id="helpers">Role-bound helpers</h3>
+      <p>Scouts, planners, reviewers, and Oracle receive bounded scope, tools, and budgets. The parent model stays pinned; automatic workers and multiple writers remain off.</p>
+    </article>
+    <article class="card">
+      <h3 id="receipt">Completion receipts</h3>
+      <p>A receipt is approved only when the trace is completed, acceptance is satisfied, and the current-tree hard gate passes. Missing verifiers or pending work remain visible risks.</p>
+    </article>
+    <article class="card">
+      <h3 id="product-views">Product views</h3>
+      <p>Preflight, live status, the activity inspector, efficiency, and orchestration policy use deterministic output; users do not need a model to remember or interpret runtime state.</p>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Daily flow</p>
+  <h2 id="usage-flow">The daily workflow does not break</h2>
+  <div class="steps">
+    <article class="step"><div><h3>Assign work as before</h3><p>Use a natural-language request or <span class="inline-code">/workflow task &lt;request&gt;</span>. Manual preflight is optional.</p></div></article>
+    <article class="step"><div><h3>The runtime records truth</h3><p>Task Contracts, context, changed files, trajectories, and checkpoints are updated from hooks and tool results rather than model memory.</p></div></article>
+    <article class="step"><div><h3>Verify the exact working tree</h3><p>Only observed exact commands that exit successfully and match the current-tree digest count as passing evidence.</p></div></article>
+    <article class="step"><div><h3>Bounded recovery or handoff</h3><p>Source repair and transient retries have ceilings. Unsafe cases return to handoff or the operator instead of continuing by guesswork.</p></div></article>
+    <article class="step"><div><h3>Completion fails closed</h3><p>A completed trace is not enough. Work plan, acceptance, changed-file integrity, and current verifier evidence must pass before approval.</p></div></article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Inspect when needed</p>
+  <h2 id="new-commands">Five commands that expose the whole flow</h2>
+  <p class="section-lead">These are inspection and diagnostic commands, not mandatory steps before every task.</p>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Preflight, activity, status, metrics, and helper policy</span><button class="clip-btn" data-clip="/task-preflight --json Review current repository state&#10;/piagent-inspector&#10;/piagent-status&#10;/usage efficiency&#10;/piagent-orchestration">Copy</button></header>
+      <pre><code>/task-preflight --json Review current repository state
+/piagent-inspector
+/piagent-status
+/usage efficiency
+/piagent-orchestration</code></pre>
+      <p>See <a href="/en/workflows">How workflows change</a> for exactly what each command reads, what it does not do, and when to use it.</p>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Automatic vs opt-in</p>
+  <h2 id="automatic-and-opt-in">What runs automatically and what requires opt-in</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Surface</th><th>Default</th><th>Behavior</th></tr></thead>
+      <tbody>
+        <tr><td>Runtime snapshots and task evidence</td><td>Automatic</td><td>Records bounded facts, journal entries, verifier evidence, recovery, and receipts.</td></tr>
+        <tr><td>Activity inspector</td><td>Automatic four-row panel, optional menu</td><td>Shows task diffs, commands, safety, and context beside the footer without calling a model or changing workflow state.</td></tr>
+        <tr><td>Solver</td><td><span class="inline-code">shadow</span></td><td>Evaluates routes without changing the parent model or taking control of the workflow.</td></tr>
+        <tr><td>Phase tools</td><td><span class="inline-code">shadow</span></td><td>Computes projections; use <span class="inline-code">PIAGENT_PHASE_TOOLS=on</span> to apply phase-specific tool visibility.</td></tr>
+        <tr><td>Recovery</td><td><span class="inline-code">on</span></td><td>Retries or repairs within ceilings; use <span class="inline-code">PIAGENT_AUTO_RECOVERY=off</span> to restore ordinary handoff.</td></tr>
+        <tr><td>Helpers</td><td><span class="inline-code">recommend</span></td><td>Explains recommendations only; <span class="inline-code">PIAGENT_HELPERS_MODE=on</span> dispatches read-only roles only when an adapter is available.</td></tr>
+        <tr><td>Parent routing and automatic workers</td><td><span class="inline-code">off</span></td><td>No automatic parent-model switch, writer dispatch, or default multi-writer behavior.</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Compatibility</p>
+  <h2 id="compatibility">No workflow rewrite or old-task migration required</h2>
+  <div class="callout">
+    <strong>Task Contract remains v2.</strong>
+    <p>Runtime snapshots, solver decisions, trajectories, recovery, and helper state use additive versioned sidecars. Existing command aliases continue to work; old state without a new projection stays unknown or unavailable instead of being upgraded into success.</p>
+  </div>
+  <div class="grid cols-2">
+    <article class="card"><h3 id="host-boundary">The host is not a sandbox</h3><p>Policy reduces mistakes inside controlled tool surfaces but does not isolate code from the operator account. External and destructive actions still require confirmation.</p></article>
+    <article class="card"><h3 id="safe-defaults">Defaults remain conservative</h3><p>Solver and phase tools remain in shadow, helpers do not auto-dispatch, and parent routing and automatic workers stay off until separate rollout evidence exists.</p></article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Try it</p>
+  <h2 id="try-directly">Test directly in a new Pi session</h2>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Read-only product walkthrough</span><button class="clip-btn" data-clip="/task-preflight --json Review this repository without modifying files&#10;/piagent-inspector&#10;/piagent-status&#10;/usage efficiency">Copy</button></header>
+      <pre><code>/task-preflight --json Review this repository without modifying files
+/piagent-inspector
+/piagent-status
+/usage efficiency</code></pre>
+      <p>After updating the package or a local checkout, start a new Pi session so the extension reloads. See the <a href="/en/commands">Command catalog</a> for every command and compatibility alias.</p>
+    </article>
+  </div>
+</section>

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

@@ -0,0 +1,81 @@
+<section class="section">
+  <p class="section-kicker">Workflow impact</p>
+  <h2 id="conclusion">No new command is mandatory in the daily flow</h2>
+  <p class="section-lead">Users still assign work with a natural-language request or <span class="inline-code">/workflow task</span>. The main change is inside the runtime: task state, trajectories, verifier evidence, recovery, and completion gates are recorded more strictly. The new commands only expose that data when needed.</p>
+  <div class="callout ok-callout">
+    <strong>Short answer</strong>
+    <p>The interaction flow is not longer. The control flow behind it is safer and fails closed when evidence is missing. A valid task does not require all four new commands.</p>
+  </div>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Moment</th><th>User action stays the same</th><th>New automatic runtime behavior</th><th>Optional inspection command</th></tr></thead>
+      <tbody>
+        <tr><td>Before a task</td><td>Send a request or <span class="inline-code">/workflow task &lt;request&gt;</span>.</td><td>Loads profile and context, classifies intent and risk, captures runtime truth, and computes a solver recommendation.</td><td><span class="inline-code">/task-preflight [--json] &lt;intent&gt;</span></td></tr>
+        <tr><td>During work</td><td>Continue the task normally.</td><td>Records the work plan, phase, changed files, tool and command results, checkpoints, helpers, and recovery events. The inspector updates below the footer.</td><td><span class="inline-code">/piagent-inspector</span> or <span class="inline-code">/piagent-status</span></td></tr>
+        <tr><td>Verify and review</td><td>Use project verification; call <span class="inline-code">/workflow review</span> when a separate review is useful.</td><td>Accepts only successful exact verifiers bound to the current working-tree identity.</td><td><span class="inline-code">/piagent-status</span></td></tr>
+        <tr><td>Completion or handoff</td><td>Receive the outcome and remaining risks as before.</td><td>Approves a receipt only when trace, work plan, acceptance, changed-file integrity, and the hard gate all pass.</td><td><span class="inline-code">/piagent-status</span></td></tr>
+        <tr><td>After a task</td><td>No new required step.</td><td>Keeps sourced telemetry without inferring quality.</td><td><span class="inline-code">/usage efficiency</span></td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Command semantics</p>
+  <h2 id="command-effects">How far the new commands affect a workflow</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Command</th><th>Reads or displays</th><th>Does not perform</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">/task-preflight</span></td><td>Intent, risk, scope, runtime, route, phase/tool/helper policy, backend, approval, and blockers.</td><td>Does not create a task, advance a phase, call a model, or grant implementation authority.</td></tr>
+        <tr><td><span class="inline-code">/piagent-status</span></td><td>Task Contract, trajectory, checkpoint, verifier, recovery, helper, resume, and terminal receipt from persisted evidence.</td><td>Does not edit files, rerun verification, retry work, or turn missing evidence into success.</td></tr>
+        <tr><td><span class="inline-code">/piagent-inspector</span></td><td>Observed task files in the four-row footer panel, exact baseline delta in the <span class="inline-code">files</span> view, current tool, command failures and blocks, safety warnings, and context budget. No argument opens the menu.</td><td>Does not edit files, execute commands, change completion state, or estimate tokens for each built-in tool.</td></tr>
+        <tr><td><span class="inline-code">/usage efficiency</span></td><td>Sourced context telemetry and task metrics; unavailable facts remain <span class="inline-code">null</span> or unavailable.</td><td>Does not grade a person or model and does not decide the completion gate.</td></tr>
+        <tr><td><span class="inline-code">/piagent-orchestration</span></td><td>Current mode, helper mode, subagent limit, review lenses, Field Guide, and writer policy.</td><td>Does not change mode, spawn a helper, or enable parallel writers.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>Only explicit opt-in changes behavior.</strong>
+    <p>These five commands are read-only. Behavior changes only when an operator deliberately enables a rollout setting such as phase tools or helper mode; parent routing, automatic workers, and multiple writers do not turn on automatically.</p>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Daily example</p>
+  <h2 id="example-flow">A complete flow can look like this</h2>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Inspect → implement → review → receipt</span><button class="clip-btn" data-clip="/task-preflight --json Fix the failing checkout test&#10;/workflow task Fix the failing checkout test and verify.&#10;/piagent-inspector&#10;/workflow review current diff&#10;/piagent-status&#10;/usage efficiency">Copy</button></header>
+      <pre><code>/task-preflight --json Fix the failing checkout test
+/workflow task Fix the failing checkout test and verify.
+/piagent-inspector
+/workflow review current diff
+/piagent-status
+/usage efficiency</code></pre>
+      <p>Only <span class="inline-code">/workflow task</span> starts implementation. The inspector opens a menu for files, commands, safety, and context; preflight, inspector, status, and efficiency are optional. Use a separate review when the scope or handoff policy calls for one.</p>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <div class="callout ok-callout">
+    <strong>Git in Pi Agent</strong>
+    <p>There is no separate <span class="inline-code">/git</span> namespace. Use <span class="inline-code">/workflow commit</span> for a reviewed local commit and <span class="inline-code">/workflow pr</span> to prepare a pull request. Actions such as <span class="inline-code">git push</span> or broad staging with <span class="inline-code">git add -A</span> still require operator confirmation.</p>
+  </div>
+  <div class="callout">
+    <strong>Solo-first orchestration</strong>
+    <p>Use <span class="inline-code">/piagent-orchestration</span> to inspect mode, subagent limits, review lenses, Field Guide, and writer policy. The parent agent owns the task by default; subagents are used only when scouting, planning, or review has an independent lane worth the token cost.</p>
+  </div>
+  <div class="command-grid">
+    <article class="command-card"><header><span>Bounded implementation</span><button class="clip-btn" data-clip="/workflow task Fix the failing checkout test and verify.">Copy</button></header><pre><code>/workflow task Fix the failing checkout test and verify.</code></pre></article>
+    <article class="command-card"><header><span>Read-only scout</span><button class="clip-btn" data-clip="/workflow scout Map the auth flow and risk areas.">Copy</button></header><pre><code>/workflow scout Map the auth flow and risk areas.</code></pre></article>
+    <article class="command-card"><header><span>Plan before coding</span><button class="clip-btn" data-clip="/workflow plan Add multi-tenant billing support.">Copy</button></header><pre><code>/workflow plan Add multi-tenant billing support.</code></pre></article>
+    <article class="command-card"><header><span>Review a diff</span><button class="clip-btn" data-clip="/workflow review current diff">Copy</button></header><pre><code>/workflow review current diff</code></pre></article>
+    <article class="command-card"><header><span>Guarded local commit</span><button class="clip-btn" data-clip="/workflow commit &quot;feat: add guarded git workflow&quot;">Copy</button></header><pre><code>/workflow commit "feat: add guarded git workflow"</code></pre></article>
+    <article class="command-card"><header><span>Prepare a pull request</span><button class="clip-btn" data-clip="/workflow pr &quot;Prepare PR for guarded git workflow&quot;">Copy</button></header><pre><code>/workflow pr "Prepare PR for guarded git workflow"</code></pre></article>
+    <article class="command-card"><header><span>Backend spec to frontend</span><button class="clip-btn" data-clip="/profile be-readonly-fe&#10;/workflow be-to-fe Implement frontend support for the new user status endpoint.">Copy</button></header><pre><code>/profile be-readonly-fe
+/workflow be-to-fe Implement frontend support for the new user status endpoint.</code></pre></article>
+    <article class="command-card"><header><span>Improve the platform</span><button class="clip-btn" data-clip="/workflow platform-improve Harden command docs and run verification.">Copy</button></header><pre><code>/workflow platform-improve Harden command docs and run verification.</code></pre></article>
+  </div>
+</section>

package/docs-site/content/index.html

@@ -12,6 +12,7 @@
   </div>
   <div class="hero-actions">
     <a class="button primary" href="/quickstart">Bắt đầu</a>
+    <a class="button" href="/whats-new">Có gì mới</a>
     <a class="button" href="/commands">Xem command</a>
     <a class="button" href="/mcp">MCP</a>
   </div>
@@ -28,6 +29,11 @@ piagent-setup</code></pre>
 <section class="section">
   <h2 id="bat-dau-tu-dau">Bắt đầu từ đâu</h2>
   <div class="card-grid">
+    <a class="doc-card" href="/whats-new">
+      <span class="card-kicker">Product update</span>
+      <h3>Có gì mới</h3>
+      <p>Runtime truth, task trajectory, recovery, helper policy và completion receipt fail-closed — phần nào tự chạy, phần nào cần opt-in.</p>
+    </a>
     <a class="doc-card" href="/quickstart">
       <span class="card-kicker">Get started</span>
       <h3>Quickstart</h3>

package/docs-site/content/quickstart.html

@@ -4,7 +4,7 @@
     <article class="step">
       <div>
         <h3 id="cai-hai-lenh">Cài — hai lệnh</h3>
-        <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.2.3</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
+        <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản host mà release hiện tại đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
         <div class="table-wrap compact-table">
           <table>
             <thead>

package/docs-site/content/runtime.html

@@ -6,8 +6,8 @@
       <pre><code>piagent-setup --mcp-preset core --subagents-preset safe</code></pre>
     </article>
     <article class="command-card">
-      <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
-      <pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+      <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
+      <pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
 npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable</code></pre>

package/docs-site/content/whats-new.html

@@ -0,0 +1,107 @@
+<section class="section">
+  <p class="section-kicker">Product stabilization</p>
+  <h2 id="thay-doi-chinh">Sáu thay đổi người dùng sẽ thấy</h2>
+  <p class="section-lead">Workflow cũ vẫn chạy. Update này đưa thêm bằng chứng runtime và các gate fail-closed vào phía sau, rồi mở những projection ngắn để người dùng kiểm tra khi cần.</p>
+  <div class="grid cols-3">
+    <article class="card">
+      <h3 id="runtime-truth">Runtime truth</h3>
+      <p>Model, provider, thinking, context window và provenance được đọc từ runtime hoặc authenticated catalog. Fact chưa có giữ là unknown, không đoán từ tên model.</p>
+    </article>
+    <article class="card">
+      <h3 id="trajectory">Task trajectory</h3>
+      <p>Task đi qua plan, execute, verify, review, handoff và terminal bằng state có replay. Event stale, sai identity hoặc corrupt sẽ fail closed.</p>
+    </article>
+    <article class="card">
+      <h3 id="recovery">Recovery và resume</h3>
+      <p>Lỗi được phân loại trước khi retry hoặc repair. Environment, provider, permission, policy và scope failure không bao giờ cấp quyền sửa source.</p>
+    </article>
+    <article class="card">
+      <h3 id="helpers">Role-bound helpers</h3>
+      <p>Scout, planner, reviewer và Oracle nhận scope/tool/budget có giới hạn. Parent model được giữ nguyên; automatic worker và multi-writer vẫn tắt.</p>
+    </article>
+    <article class="card">
+      <h3 id="receipt">Completion receipt</h3>
+      <p>Receipt chỉ approved khi trace completed, acceptance satisfied và hard gate trên working tree hiện tại pass. Thiếu verifier hoặc work plan còn pending phải giữ remaining risk.</p>
+    </article>
+    <article class="card">
+      <h3 id="product-views">Product views</h3>
+      <p>Preflight, live status, activity inspector, efficiency và orchestration policy có output deterministic; người dùng không cần nhờ model nhớ hoặc diễn giải state.</p>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Daily flow</p>
+  <h2 id="luong-su-dung">Luồng dùng hằng ngày không bị phá</h2>
+  <div class="steps">
+    <article class="step"><div><h3>Giao task như trước</h3><p>Dùng prompt tự nhiên hoặc <span class="inline-code">/workflow task &lt;request&gt;</span>. Không cần gọi preflight thủ công.</p></div></article>
+    <article class="step"><div><h3>Runtime tự ghi nhận truth</h3><p>Task Contract, context, changed files, trajectory và checkpoint được cập nhật từ hook/tool result thay vì trí nhớ của model.</p></div></article>
+    <article class="step"><div><h3>Verify đúng working tree</h3><p>Chỉ exact command đã quan sát, exit thành công và khớp current-tree digest mới được tính là passing evidence.</p></div></article>
+    <article class="step"><div><h3>Recovery hoặc handoff có giới hạn</h3><p>Source repair và transient retry có ceiling. Trường hợp không an toàn chuyển sang handoff/operator thay vì tiếp tục đoán.</p></div></article>
+    <article class="step"><div><h3>Completion fail closed</h3><p>Trace completed không đủ. Work plan, acceptance, changed-file integrity và verifier hiện hành phải cùng pass trước khi receipt approved.</p></div></article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Inspect when needed</p>
+  <h2 id="command-moi">Năm command để nhìn xuyên suốt luồng</h2>
+  <p class="section-lead">Đây là command quan sát và chẩn đoán, không phải bước bắt buộc trước mỗi task.</p>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Preflight, activity, status, metrics và helper policy</span><button class="clip-btn" data-clip="/task-preflight --json Review current repository state&#10;/piagent-inspector&#10;/piagent-status&#10;/usage efficiency&#10;/piagent-orchestration">Lấy lệnh</button></header>
+      <pre><code>/task-preflight --json Review current repository state
+/piagent-inspector
+/piagent-status
+/usage efficiency
+/piagent-orchestration</code></pre>
+      <p>Xem <a href="/workflows">Workflow thay đổi thế nào</a> để biết chính xác từng command đọc gì, không làm gì và nên dùng ở thời điểm nào.</p>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Automatic vs opt-in</p>
+  <h2 id="tu-dong-va-opt-in">Cái gì tự chạy, cái gì cần bật rõ ràng</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Surface</th><th>Mặc định</th><th>Hành vi</th></tr></thead>
+      <tbody>
+        <tr><td>Runtime snapshot + task evidence</td><td>Tự động</td><td>Ghi fact, journal, verifier, recovery và receipt có giới hạn.</td></tr>
+        <tr><td>Activity inspector</td><td>Panel bốn dòng tự động, menu tùy chọn</td><td>Hiện task diff, command, safety và context sát footer; không gọi model và không đổi workflow state.</td></tr>
+        <tr><td>Solver</td><td><span class="inline-code">shadow</span></td><td>Đánh giá route nhưng không đổi parent model hoặc tự chiếm quyền workflow.</td></tr>
+        <tr><td>Phase tools</td><td><span class="inline-code">shadow</span></td><td>Tính projection; dùng <span class="inline-code">PIAGENT_PHASE_TOOLS=on</span> để áp tool visibility theo phase.</td></tr>
+        <tr><td>Recovery</td><td><span class="inline-code">on</span></td><td>Tự retry/repair trong ceiling; dùng <span class="inline-code">PIAGENT_AUTO_RECOVERY=off</span> để quay về ordinary handoff.</td></tr>
+        <tr><td>Helpers</td><td><span class="inline-code">recommend</span></td><td>Chỉ giải thích recommendation; <span class="inline-code">PIAGENT_HELPERS_MODE=on</span> chỉ dispatch read-only role qua adapter có sẵn.</td></tr>
+        <tr><td>Parent routing + automatic worker</td><td><span class="inline-code">off</span></td><td>Không tự đổi parent model, không tự bật writer và không có multi-writer mặc định.</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Compatibility</p>
+  <h2 id="tuong-thich">Không cần đổi thói quen hoặc migrate task cũ</h2>
+  <div class="callout">
+    <strong>Task Contract vẫn là v2.</strong>
+    <p>Runtime snapshot, solver, trajectory, recovery và helper state là sidecar versioned/additive. Alias command cũ vẫn hoạt động; state cũ thiếu projection mới phải hiện unknown/unavailable thay vì được nâng cấp thành success.</p>
+  </div>
+  <div class="grid cols-2">
+    <article class="card"><h3 id="host-boundary">Host không phải sandbox</h3><p>Policy giảm lỗi trong tool surface được kiểm soát nhưng không cô lập code khỏi account của operator. External và destructive action vẫn cần confirmation.</p></article>
+    <article class="card"><h3 id="safe-defaults">Default giữ conservative</h3><p>Solver/phase tools chưa được promote khỏi shadow, helpers chưa tự dispatch, parent routing và automatic worker vẫn off cho tới khi có rollout evidence riêng.</p></article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Try it</p>
+  <h2 id="test-truc-tiep">Test trực tiếp sau khi mở Pi session mới</h2>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Read-only product walkthrough</span><button class="clip-btn" data-clip="/task-preflight --json Review this repository without modifying files&#10;/piagent-inspector&#10;/piagent-status&#10;/usage efficiency">Lấy lệnh</button></header>
+      <pre><code>/task-preflight --json Review this repository without modifying files
+/piagent-inspector
+/piagent-status
+/usage efficiency</code></pre>
+      <p>Sau update package hoặc local checkout, mở Pi session mới để extension được reload. Dùng <a href="/commands">Command catalog</a> cho toàn bộ command và alias.</p>
+    </article>
+  </div>
+</section>

package/docs-site/content/workflows.html

@@ -1,3 +1,63 @@
+<section class="section">
+  <p class="section-kicker">Workflow impact</p>
+  <h2 id="ket-luan">Không có command bắt buộc mới trong daily flow</h2>
+  <p class="section-lead">Người dùng vẫn giao việc bằng prompt tự nhiên hoặc <span class="inline-code">/workflow task</span>. Thay đổi chính nằm trong runtime: task state, trajectory, verifier evidence, recovery và completion gate được ghi nhận chặt hơn. Các command mới chỉ mở cửa sổ đọc những dữ liệu đó khi cần.</p>
+  <div class="callout ok-callout">
+    <strong>Kết luận ngắn</strong>
+    <p>Luồng thao tác không dài thêm. Luồng kiểm soát phía sau an toàn hơn và fail closed khi thiếu bằng chứng. Không cần chạy đủ bốn command mới để một task hợp lệ.</p>
+  </div>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Thời điểm</th><th>Người dùng làm như trước</th><th>Runtime mới tự xử lý</th><th>Command xem thêm, không bắt buộc</th></tr></thead>
+      <tbody>
+        <tr><td>Trước task</td><td>Gửi prompt hoặc <span class="inline-code">/workflow task &lt;request&gt;</span>.</td><td>Đọc profile/context, phân loại intent và risk, chụp runtime truth và solver recommendation.</td><td><span class="inline-code">/task-preflight [--json] &lt;intent&gt;</span></td></tr>
+        <tr><td>Đang làm</td><td>Tiếp tục trao đổi trong cùng task.</td><td>Ghi work plan, phase, changed files, tool/command result, checkpoint, helper và recovery event. Inspector tự cập nhật dưới footer.</td><td><span class="inline-code">/piagent-inspector</span> hoặc <span class="inline-code">/piagent-status</span></td></tr>
+        <tr><td>Verify và review</td><td>Dùng verify của project; gọi <span class="inline-code">/workflow review</span> khi cần review riêng.</td><td>Chỉ nhận exact verifier thành công và khớp working-tree identity hiện tại.</td><td><span class="inline-code">/piagent-status</span></td></tr>
+        <tr><td>Hoàn tất hoặc handoff</td><td>Nhận kết quả và remaining risk như trước.</td><td>Receipt chỉ approved khi trace, work plan, acceptance, changed-file integrity và hard gate cùng pass.</td><td><span class="inline-code">/piagent-status</span></td></tr>
+        <tr><td>Sau task</td><td>Không có bước bắt buộc mới.</td><td>Giữ telemetry có nguồn, không tự suy diễn chất lượng.</td><td><span class="inline-code">/usage efficiency</span></td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Command semantics</p>
+  <h2 id="command-anh-huong-gi">Command mới ảnh hưởng workflow đến đâu</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Command</th><th>Đọc hoặc hiển thị</th><th>Không thực hiện</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">/task-preflight</span></td><td>Intent, risk, scope, runtime, route, phase/tool/helper policy, backend, approval và blocker.</td><td>Không tạo task, không advance phase, không gọi model và không cấp quyền implementation.</td></tr>
+        <tr><td><span class="inline-code">/piagent-status</span></td><td>Task Contract, trajectory, checkpoint, verifier, recovery, helper, resume và terminal receipt từ persisted evidence.</td><td>Không sửa file, không chạy lại verify, không retry và không biến state thiếu evidence thành success.</td></tr>
+        <tr><td><span class="inline-code">/piagent-inspector</span></td><td>Observed task files trên panel bốn dòng sát footer, exact baseline delta trong view <span class="inline-code">files</span>, tool hiện tại, command fail/block, safety warning và context budget. Không tham số sẽ mở menu.</td><td>Không sửa file, không chạy command, không đổi completion state và không ước lượng token theo từng built-in tool.</td></tr>
+        <tr><td><span class="inline-code">/usage efficiency</span></td><td>Context telemetry và task metrics có nguồn; fact không đo được giữ <span class="inline-code">null</span> hoặc unavailable.</td><td>Không chấm chất lượng con người/model và không quyết định completion gate.</td></tr>
+        <tr><td><span class="inline-code">/piagent-orchestration</span></td><td>Mode, helper mode, giới hạn subagent, review lenses, Field Guide và writer policy hiện hành.</td><td>Không đổi mode, không spawn helper và không bật parallel writer.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>Chỉ opt-in mới đổi hành vi.</strong>
+    <p>Năm command trên là read-only. Hành vi chỉ đổi khi operator chủ động bật setting rollout như phase tools hoặc helper mode; parent routing, automatic worker và multi-writer vẫn không tự bật.</p>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Daily example</p>
+  <h2 id="luong-mau">Một luồng đầy đủ có thể dùng như sau</h2>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Inspect → implement → review → receipt</span><button class="clip-btn" data-clip="/task-preflight --json Fix the failing checkout test&#10;/workflow task Fix the failing checkout test and verify.&#10;/piagent-inspector&#10;/workflow review current diff&#10;/piagent-status&#10;/usage efficiency">Lấy lệnh</button></header>
+      <pre><code>/task-preflight --json Fix the failing checkout test
+/workflow task Fix the failing checkout test and verify.
+/piagent-inspector
+/workflow review current diff
+/piagent-status
+/usage efficiency</code></pre>
+      <p>Chỉ dòng <span class="inline-code">/workflow task</span> khởi chạy implementation. Inspector mở menu để xem file/command/safety/context; preflight, inspector, status và efficiency đều tùy chọn. Review riêng dùng khi scope hoặc quy trình handoff yêu cầu.</p>
+    </article>
+  </div>
+</section>
+
 <section class="section">
   <div class="callout ok-callout">
     <strong>Git trong Pi Agent</strong>

package/docs-site/context-engine.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="Index local, retrieval có xếp hạng, tool loading theo task, semantic compaction và telemetry minh bạch cho Agent Watch." />
     <meta name="theme-color" content="#050505" />
     <link rel="canonical" href="https://piagent.io.vn/context-engine" />
+    <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/context-engine" />
+    <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/context-engine" />
+    <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/context-engine" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <meta property="og:title" content="Ít context hơn, giữ nguyên chất lượng model · Pi Agent Platform Docs" />
     <meta property="og:description" content="Index local, retrieval có xếp hạng, tool loading theo task, semantic compaction và telemetry minh bạch cho Agent Watch." />
@@ -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.3.0-ie.8 docs · VI</span>
+        <nav class="language-switch" aria-label="Ngôn ngữ">
+          <a class="language-option current" href="/context-engine" hreflang="vi" lang="vi" aria-current="true">VI</a>
+          <a class="language-option" href="/en/context-engine" 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>
 
@@ -54,6 +60,7 @@
             <p class="nav-title">Get started</p>
             <a class="nav-link" href="/">Overview</a>
             <a class="nav-link" href="/quickstart">Quickstart</a>
+            <a class="nav-link" href="/whats-new">Có gì mới</a>
             <a class="nav-link" href="/scope">Phạm vi platform</a>
           </div>
           <div class="nav-group">
@@ -162,10 +169,10 @@ piagent-context efficiency</code></pre>
 
             <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/context-engine" hreflang="en">English</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>