@piagent/platform 1.2.16 → 1.3.0-ie.8

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

@@ -0,0 +1,51 @@
+<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">Adaptive runtime</p>
+    <h2 id="adaptive-runtime">Piagent now separates runtime decisions from Pi wiring</h2>
+    <p>The harness keeps the model choice intact, but every task gets a smaller, cited context plan, durable task journal, and explicit recovery decision.</p>
+  </div>
+  <div class="grid cols-3">
+    <article class="card"><h3>Context planner</h3><p><span class="inline-code">runtime/context/adaptive-planner.ts</span> chooses budget, retrieval lane, code inclusion, and a plan receipt from phase, context pressure, model capability, and thinking level.</p></article>
+    <article class="card"><h3>Task journal</h3><p><span class="inline-code">extensions/task-journal.js</span> records start, progress, mutation, verifier, and completion checkpoints. Resume trusts the task contract first; retention compaction preserves hash anchors.</p></article>
+    <article class="card"><h3>Repository memory</h3><p><span class="inline-code">extensions/repository-memory.js</span> stores only cited, expiring facts and rejects raw prompts, outputs, OAuth material, API keys, and secrets. Hints use only unused context-plan budget.</p></article>
+    <article class="card"><h3>Model capability</h3><p><span class="inline-code">runtime/model/capabilities.ts</span> reads model family, context window, and thinking level as budget signals without switching providers or requiring API keys.</p></article>
+    <article class="card"><h3>Verification intelligence</h3><p><span class="inline-code">extensions/verification-intelligence.js</span> classifies failures and chooses a targeted verifier from task scope; mixed frontend/backend scope uses the full source verifier.</p></article>
+    <article class="card"><h3>Execution backend</h3><p><span class="inline-code">extensions/execution-backend.js</span> keeps local Pi OAuth as owner and blocks mutation when a requested experimental adapter is unavailable.</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>Task journal and checkpoints</td><td>Runtime</td><td><span class="inline-code">.pi/piagent-state/task-journal/</span></td><td>No</td></tr>
+        <tr><td>Repository memory facts</td><td>Runtime</td><td><span class="inline-code">.pi/piagent-state/repository-memory/</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>

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

@@ -0,0 +1,184 @@
+<section class="benchmark-summary" aria-labelledby="benchmark-verdict">
+  <div class="benchmark-verdict">
+    <div>
+      <p class="section-kicker">Production V1 · historical public regression evidence</p>
+      <h2 id="benchmark-verdict">Piagent scores 9.92/10</h2>
+      <p>It resolved all 54 tasks, maintained 10/10 Quality, Safety, and Reliability, and used 51.11% fewer fresh tokens than the <code>codex-cli</code> surface in paired measurement.</p>
+    </div>
+    <div class="benchmark-verdict-score" aria-label="Overall score 9.92 out of 10">
+      <strong>9.92</strong>
+      <span>Overall / 10</span>
+    </div>
+  </div>
+
+  <div class="benchmark-metrics" aria-label="Headline metrics">
+    <div class="benchmark-metric"><span>Tasks resolved</span><strong>54/54</strong><small>100% on both surfaces</small></div>
+    <div class="benchmark-metric"><span>Fresh tokens</span><strong>-51.11%</strong><small>paired geometric mean</small></div>
+    <div class="benchmark-metric"><span>Token wins</span><strong>47/54</strong><small><code>codex-cli</code> won 7 pairs</small></div>
+    <div class="benchmark-metric"><span>Infrastructure</span><strong>0 retries</strong><small>108 valid runs</small></div>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Measurement configuration</p>
+  <h2 id="configuration">Same model, same tasks, automatic grading</h2>
+  <p class="section-lead">The suite runs Piagent and the <code>codex-cli</code> surface in separate clean workspaces with matching fixtures, generated variants, and hidden verifiers. Usage is parsed from agent JSONL rather than entered manually.</p>
+  <dl class="benchmark-facts">
+    <div><dt>Model</dt><dd><code>openai-codex/gpt-5.6-sol</code></dd></div>
+    <div><dt>Thinking</dt><dd><code>xhigh</code></dd></div>
+    <div><dt>Matrix</dt><dd>18 families × 3 repeats × 2 surfaces</dd></div>
+    <div><dt>Total sessions</dt><dd>108</dd></div>
+    <div><dt>Baseline</dt><dd><code>codex-cli</code> controlled mode</dd></div>
+    <div><dt>Duration</dt><dd>1 hour 49 minutes</dd></div>
+  </dl>
+  <div class="callout ok-callout">
+    <strong>Isolated control surface</strong>
+    <p><code>codex-cli</code> uses a temporary home per session and loads no global instructions, plugins, apps, browser, or multi-agent configuration. Both surfaces use the same model and thinking level with a 900-second timeout per session.</p>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Score bands</p>
+  <h2 id="scores">Token reduction does not trade away quality</h2>
+  <p class="section-lead">Overall is calculated only when quality, safety, reliability, and workflow gates all pass. The <code>codex-cli</code> surface is the baseline and does not receive the harness-specific Workflow or Overall score.</p>
+  <div class="benchmark-score-chart" role="img" aria-label="Piagent scores Quality 10, Safety 10, Reliability 10, Workflow 9.58, Efficiency 10, and Overall 9.92 out of 10">
+    <div class="benchmark-score-row"><span>Quality</span><div class="benchmark-track"><i style="--bar-size: 100%"></i></div><strong>10.00</strong></div>
+    <div class="benchmark-score-row"><span>Safety</span><div class="benchmark-track"><i style="--bar-size: 100%"></i></div><strong>10.00</strong></div>
+    <div class="benchmark-score-row"><span>Reliability</span><div class="benchmark-track"><i style="--bar-size: 100%"></i></div><strong>10.00</strong></div>
+    <div class="benchmark-score-row"><span>Workflow</span><div class="benchmark-track"><i style="--bar-size: 95.8%"></i></div><strong>9.58</strong></div>
+    <div class="benchmark-score-row"><span>Efficiency</span><div class="benchmark-track"><i style="--bar-size: 100%"></i></div><strong>10.00</strong></div>
+    <div class="benchmark-score-row overall"><span>Overall</span><div class="benchmark-track"><i style="--bar-size: 99.2%"></i></div><strong>9.92</strong></div>
+  </div>
+  <div class="table-wrap benchmark-table-wrap">
+    <table>
+      <thead><tr><th>Band</th><th>Piagent</th><th>codex-cli</th><th>Evidence</th></tr></thead>
+      <tbody>
+        <tr><td>Quality</td><td><strong>10.00</strong></td><td>10.00</td><td>48/48 source tasks passed hidden graders</td></tr>
+        <tr><td>Safety</td><td><strong>10.00</strong></td><td>10.00</td><td>54/54 sessions stayed in scope and emitted no forbidden output</td></tr>
+        <tr><td>Reliability</td><td><strong>10.00</strong></td><td>10.00</td><td>54/54 resolved across all 18 families</td></tr>
+        <tr><td>Workflow</td><td><strong>9.58</strong></td><td>n/a</td><td>Passed the 9.00 gate with every evidence gap disclosed</td></tr>
+        <tr><td>Efficiency</td><td><strong>10.00</strong></td><td>5.00 baseline</td><td>54 valid usage pairs with the same model and thinking</td></tr>
+        <tr><td>Overall</td><td><strong>9.92</strong></td><td>n/a</td><td>Quality 45%, reliability 15%, workflow 20%, efficiency 20%</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Tokens and tools</p>
+  <h2 id="tokens">Piagent uses less fresh context</h2>
+  <p class="section-lead">The bars show independent medians across 54 runs per surface. The Efficiency score does not divide these aggregate medians; it uses matched scenario-and-repeat ratios to avoid distortion from task size.</p>
+  <div class="benchmark-legend" aria-label="Chart legend">
+    <span><i class="piagent-swatch"></i>Piagent</span>
+    <span><i class="codex-swatch"></i>codex-cli</span>
+  </div>
+  <div class="benchmark-usage-chart" aria-label="Median usage comparison between Piagent and codex-cli">
+    <div class="benchmark-usage-group">
+      <h3>Fresh tokens</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 39.88%"></i></div><strong>7,368</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>18,476</strong></div>
+    </div>
+    <div class="benchmark-usage-group">
+      <h3>Input excluding cache</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 48.98%"></i></div><strong>6,801</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>13,885</strong></div>
+    </div>
+    <div class="benchmark-usage-group">
+      <h3>Output</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 39.71%"></i></div><strong>913</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>2,299</strong></div>
+    </div>
+    <div class="benchmark-usage-group">
+      <h3>Tool calls</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 62.5%"></i></div><strong>5</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>8</strong></div>
+    </div>
+  </div>
+  <div class="table-wrap benchmark-table-wrap">
+    <table>
+      <thead><tr><th>Median per run</th><th>Piagent</th><th>codex-cli</th></tr></thead>
+      <tbody>
+        <tr><td>Input excluding cache</td><td><strong>6,801</strong></td><td>13,885</td></tr>
+        <tr><td>Output</td><td><strong>913</strong></td><td>2,299</td></tr>
+        <tr><td>Cache read</td><td><strong>7,680</strong></td><td>78,208</td></tr>
+        <tr><td>Reasoning included in output</td><td><strong>414</strong></td><td>592</td></tr>
+        <tr><td>Fresh tokens</td><td><strong>7,368</strong></td><td>18,476</td></tr>
+        <tr><td>Tool calls</td><td><strong>5</strong></td><td>8</td></tr>
+        <tr><td>Cost</td><td><strong>$0.059141</strong></td><td>n/a from Codex OAuth JSONL</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="benchmark-paired">
+    <div class="benchmark-paired-head">
+      <div><span>Fresh-token pair wins</span><strong>47 Piagent · 7 codex-cli · 0 ties</strong></div>
+      <div><span>Median paired delta</span><strong>-7,870 tokens</strong></div>
+    </div>
+    <div class="benchmark-win-track" role="img" aria-label="Piagent won 47 of 54 pairs and codex-cli won 7">
+      <i class="piagent-win" style="--bar-size: 87.04%"></i>
+      <i class="codex-win" style="--bar-size: 12.96%"></i>
+    </div>
+    <p>Paired geometric mean ratio: <strong>0.4889</strong>. The 95% confidence interval is <strong>0.3809–0.6276</strong>, whose upper bound remains below the 1.0 baseline, so the token-saving claim is allowed. Across the full benchmark, Piagent used 529,932 fresh tokens versus 1,006,150 for <code>codex-cli</code>; recorded Piagent cost was $5.321.</p>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Coverage</p>
+  <h2 id="coverage">Six domains with three families each</h2>
+  <div class="benchmark-categories">
+    <div><span>Backend</span><strong>10.00</strong><p>Authorization, money rounding, cache isolation</p></div>
+    <div><span>Frontend</span><strong>10.00</strong><p>Async response, Unicode search, pagination</p></div>
+    <div><span>Data</span><strong>10.00</strong><p>Quoted CSV, stable deduplication, schema migration</p></div>
+    <div><span>Platform</span><strong>10.00</strong><p>Config precedence, CLI parsing, workspace order</p></div>
+    <div><span>Reliability</span><strong>10.00</strong><p>Bounded retry, expiry, incident diagnosis</p></div>
+    <div><span>Security</span><strong>10.00</strong><p>Secret refusal, prompt injection, audit history</p></div>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Benchmark bands</p>
+  <h2 id="benchmark-bands">Use the right suite for the decision</h2>
+  <div class="table-wrap benchmark-table-wrap">
+    <table>
+      <thead><tr><th>Band</th><th>When to use it</th><th>Minimum evidence</th><th>Claim allowed</th></tr></thead>
+      <tbody>
+        <tr><td>Core</td><td>Fast local smoke before release work</td><td>4 scenarios, 1 repeat, hidden verifier</td><td>Regression only</td></tr>
+        <tr><td>Production</td><td>Public regression for a release candidate</td><td>18 scenarios, 3 repeats, <span class="inline-code">piagent</span> vs baseline</td><td>Claims stay bounded to the observed public suite; outcome coverage, comparable CI, and failure-aware effort are separate</td></tr>
+        <tr><td>Capability</td><td>Find the harness capability ceiling</td><td>4 large multi-file/multi-component tasks with reference and mutation checks</td><td>Hill-climbing, not a release or generalization gate</td></tr>
+        <tr><td>Long-horizon</td><td>Recovery/context changes and large-repository adoption</td><td>Planned dedicated paid suite; today run Production plus deterministic crash/replay tests</td><td>No public long-horizon score until that suite ships</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>A benchmark must state its claim tier; it is not marketing copy.</strong>
+    <p>A version should not claim token savings unless quality/reliability, paired candidate-regression, outcome coverage, comparable-efficiency, failure-aware effort, scope/safety, and protocol gates pass. Raw Pi is a causal harness ablation; <code>codex-cli</code> is only an external product reference.</p>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Provenance</p>
+  <h2 id="transparency">Interpret results within their measured scope</h2>
+  <div class="table-wrap benchmark-table-wrap">
+    <table>
+      <tbody>
+        <tr><th>Run</th><td><code>production-v1-20260802T153320Z-11f3d0</code></td></tr>
+        <tr><th>Suite digest</th><td><code>90a44ac4f5d4ec11772eac00f4f984d78c6962d116581ca29ab6b8760c8f9171</code></td></tr>
+        <tr><th>Runtime</th><td>Pi 0.82.0 · <code>codex-cli 0.146.0-alpha.9.2</code> · Node 24.11.1</td></tr>
+        <tr><th>Verdict</th><td><code>piagent-more-efficient</code> · every production gate passed</td></tr>
+        <tr><th>Release mapping</th><td>Measured on the candidate before metadata bump; the same logic shipped as v1.2.12.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>Limits of the conclusion</strong>
+    <p>This is a maintainer-built public synthetic regression, not an independent benchmark proving Piagent is better for every repository or model. Generated values do not create independent task families. Generalization requires an external family-disjoint holdout, a reference/mutation/human-calibration manifest, a frozen candidate, and real shadow/canary tasks.</p>
+  </div>
+  <div class="command-grid">
+    <div class="command-card">
+      <header><span>Run the production benchmark</span><button class="clip-btn" data-clip="piagent-benchmark --production --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-sol --thinking xhigh">Copy</button></header>
+      <pre><code>piagent-benchmark --production \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh</code></pre>
+    </div>
+  </div>
+</section>

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

@@ -0,0 +1,76 @@
+<section class="section">
+  <div class="grid cols-2">
+    <article class="card">
+      <h3 id="session-basics">Session basics</h3>
+      <div class="tag-list"><span class="tag">/login</span><span class="tag">/model</span><span class="tag">/commands</span><span class="tag">/piagent-status</span><span class="tag">/piagent-inspector</span><span class="tag">/piagent-orchestration</span><span class="tag">/usage</span><span class="tag">/usage efficiency</span><span class="tag">/task-preflight</span><span class="tag">/context preflight</span><span class="tag">/name</span><span class="tag">/fresh</span><span class="tag">/session</span></div>
+      <p>Set up a session, select a model, inspect profile, usage, or orchestration state, and decide whether a large task needs a fresh session.</p>
+    </article>
+    <article class="card">
+      <h3 id="project-profile">Project profile</h3>
+      <div class="tag-list"><span class="tag">/profile</span><span class="tag">/profile list</span><span class="tag">/profile auto</span><span class="tag">/profile setup</span><span class="tag">/profile tech</span><span class="tag">/profile tech setup</span><span class="tag">/profile fullstack</span><span class="tag">/profile be-fe</span></div>
+      <p>Apply a profile directly or use a deterministic selector for the profile and tech stack. Output stays compact and does not require model interpretation.</p>
+    </article>
+    <article class="card">
+      <h3 id="implementation-workflow">Implementation workflow</h3>
+      <div class="tag-list"><span class="tag">/workflow</span><span class="tag">/workflow task</span><span class="tag">/workflow plan</span><span class="tag">/workflow review</span><span class="tag">/workflow scout</span><span class="tag">/workflow discuss</span></div>
+      <p>Packages context loading, task contracts, implementation, verification evidence, and final handoff.</p>
+    </article>
+    <article class="card">
+      <h3 id="git-handoff">Git handoff</h3>
+      <div class="tag-list"><span class="tag">/workflow commit</span><span class="tag">/workflow pr</span><span class="tag">git status</span><span class="tag">git diff</span></div>
+      <p>There is no <span class="inline-code">/git</span> namespace. Commit and PR flows use workflow guards; pushes and broad staging such as <span class="inline-code">git add -A</span> require confirmation.</p>
+    </article>
+    <article class="card">
+      <h3 id="fresh-sessions">Fresh sessions</h3>
+      <div class="tag-list"><span class="tag">/fresh task</span><span class="tag">/fresh scout</span><span class="tag">/fresh be-to-fe</span></div>
+      <p>Start a clean workflow when the current context is heavy or belongs to a different task.</p>
+    </article>
+    <article class="card">
+      <h3 id="mcp">MCP</h3>
+      <div class="tag-list"><span class="tag">/mcp</span><span class="tag">piagent-mcp</span></div>
+      <p>Inspect and configure tool servers with the core, popular, or design presets.</p>
+    </article>
+    <article class="card">
+      <h3 id="subagents">Subagents</h3>
+      <div class="tag-list"><span class="tag">/subagents-doctor</span><span class="tag">/subagents-models</span><span class="tag">/subagents-fleet</span><span class="tag">/subagent-cost</span></div>
+      <p>Inspect runtime health, model routing, background runs, and cost. Daily work remains solo-first; subagents are reserved for independent scouting, planning, or review lanes.</p>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <p class="section-kicker">Product visibility</p>
+  <h2 id="product-status-commands">Inspect runtime decisions</h2>
+  <p class="section-lead">These commands read deterministic state without asking a model to interpret it. They are optional in the daily workflow.</p>
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Preflight before a task</span><button class="clip-btn" data-clip="/task-preflight --json Review current repository state">Copy</button></header>
+      <pre><code>/task-preflight --json Review current repository state</code></pre>
+      <p>Inspect intent, risk, scope, runtime, solver route, phases, tool and helper recommendations, backend, approvals, and blockers before starting.</p>
+    </article>
+    <article class="command-card">
+      <header><span>Live task status</span><button class="clip-btn" data-clip="/piagent-status">Copy</button></header>
+      <pre><code>/piagent-status</code></pre>
+      <p>Read the Task Contract, checkpoints, verifier evidence, recovery, helpers, resume state, and terminal receipt. Approval requires the current-tree hard completion gate to pass.</p>
+    </article>
+    <article class="command-card">
+      <header><span>Activity, diff, and context</span><button class="clip-btn" data-clip="/piagent-inspector">Copy</button></header>
+      <pre><code>/piagent-inspector</code></pre>
+      <p>One menu for <span class="inline-code">summary</span>, <span class="inline-code">files</span>, <span class="inline-code">commands</span>, <span class="inline-code">security</span>, <span class="inline-code">context</span>, and <span class="inline-code">toggle</span>. A four-row panel appears automatically just above the native footer: green is healthy, yellow needs attention, and red marks failures, safety warnings, or context at 80% and above. The command reads local state without calling a model.</p>
+    </article>
+    <article class="command-card">
+      <header><span>Sourced efficiency</span><button class="clip-btn" data-clip="/usage efficiency">Copy</button></header>
+      <pre><code>/usage efficiency</code></pre>
+      <p>Inspect context and tool utilization, verification, repair, retries, and helper usage. Runtime values that cannot be measured stay <span class="inline-code">null</span>.</p>
+    </article>
+    <article class="command-card">
+      <header><span>Helper policy</span><button class="clip-btn" data-clip="/piagent-orchestration">Copy</button></header>
+      <pre><code>/piagent-orchestration</code></pre>
+      <p>Inspect the solo-first policy, read-only roles, reviewer or Oracle recommendations, owned budgets, and the one-writer invariant.</p>
+    </article>
+  </div>
+  <div class="callout">
+    <strong>Sourced diffs, no token estimates.</strong>
+    <p>The footer panel uses observed task files for fast updates; the <span class="inline-code">files</span> view computes the exact snapshot delta and marks <span class="inline-code">mixed-working-tree</span> when a task touches a file that was already dirty. Pi exposes model usage by turn and session, so per-built-in-tool tokens remain unavailable.</p>
+  </div>
+</section>

package/docs-site/content/en/context-engine.html

@@ -0,0 +1,30 @@
+<section class="section">
+  <div class="grid cols-3">
+    <article class="card"><h3 id="dynamic-tools">Task-driven tools</h3><p>Pi includes governance, policy, retrieval, knowledge, onboarding, or usage guidance in the prompt only when the task needs it. The runtime guard remains active in the background.</p></article>
+    <article class="card"><h3 id="local-index">Local index</h3><p>FTS5, symbols, and the import graph live under <span class="inline-code">.pi/piagent-state/context-engine/</span>. Storage is restricted to the current OS account; policy changes retry FTS rebuild and VACUUM until purging completes.</p></article>
+    <article class="card"><h3 id="ranked-context">Ranked context</h3><p>Explicit paths, lexical matches, symbols, Git signals, test relationships, positive feedback, and graph rank are combined before packing into a hard token budget.</p></article>
+    <article class="card"><h3 id="semantic-compact">Semantic compaction</h3><p>Preserves the goal, decisions, changed files, verification, and blockers. Removes repeated logs, source excerpts, and superseded plans.</p></article>
+    <article class="card"><h3 id="test-impact">Test impact</h3><p>Walks the import graph backward from changed files to suggest dependents and focused tests before running the full suite.</p></article>
+    <article class="card"><h3 id="agent-watch">Agent Watch</h3><p>Local events include session, model, thinking, tool surface, retrieval confidence, context-use ratio, and waste metrics without storing raw prompts or outputs a second time.</p></article>
+  </div>
+</section>
+
+<section class="section">
+  <div class="callout">
+    <strong>The index contains source bodies</strong>
+    <p>Protected paths and secret files are excluded. The directory uses mode <span class="inline-code">0700</span>; database, WAL, and SHM files use <span class="inline-code">0600</span>. Normal refresh uses SQLite core and FTS5 secure delete. Full FTS rebuild and VACUUM run only when exclusion policy changes or an interrupted purge must resume, not on every prompt or refresh.</p>
+  </div>
+</section>
+
+<section class="section">
+  <div class="command-grid">
+    <article class="command-card"><header><span>Inside Pi</span><button class="clip-btn" data-clip="/context index&#10;/context rebuild&#10;/context pack Fix invoice calculation&#10;/context impact&#10;/usage efficiency">Copy</button></header><pre><code>/context index
+/context rebuild
+/context pack Fix invoice calculation
+/context impact
+/usage efficiency</code></pre></article>
+    <article class="command-card"><header><span>From a terminal</span><button class="clip-btn" data-clip="piagent-context rebuild&#10;piagent-context pack &quot;Fix invoice calculation&quot; --tokens 4000&#10;piagent-context efficiency">Copy</button></header><pre><code>piagent-context rebuild
+piagent-context pack "Fix invoice calculation" --tokens 4000
+piagent-context efficiency</code></pre></article>
+  </div>
+</section>

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

@@ -0,0 +1,91 @@
+<section class="hero">
+  <p class="eyebrow">Team operating docs</p>
+  <h1>A reusable Pi runtime for every project.</h1>
+  <p>
+    These docs bring installation, profiles, permissions, MCP, security, and workflows into one place. A new team member can find the right command, choose a safe mode, and understand the operating boundary without rebuilding the process in a prompt.
+  </p>
+  <div class="owner-strip" aria-label="Project information">
+    <span class="owner-label">Project links</span>
+    <a href="https://piagent.io.vn/en/" target="_blank" rel="noopener noreferrer">Docs · piagent.io.vn</a>
+    <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub · Vt-mmm/piagent</a>
+    <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook · Vinh Tam</a>
+  </div>
+  <div class="hero-actions">
+    <a class="button primary" href="/en/quickstart">Get started</a>
+    <a class="button" href="/en/whats-new">What’s new</a>
+    <a class="button" href="/en/commands">View commands</a>
+    <a class="button" href="/en/mcp">MCP</a>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="install">Install with two commands</h2>
+  <p>Requires Node.js <span class="inline-code">&gt;=22.19.0</span>. Run these commands from the project you want to configure.</p>
+  <pre><code>npm install -g @piagent/platform
+piagent-setup</code></pre>
+  <p><span class="inline-code">piagent-setup</span> installs the pinned Pi Coding Agent host, installs the Pi package, initializes the current directory, and runs doctor. It also installs the MCP baseline and subagents; skip them with <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, or <span class="inline-code">--global-only</span>. See the <a href="/en/quickstart">Quickstart</a> for the complete flow.</p>
+</section>
+
+<section class="section">
+  <h2 id="where-to-start">Where to start</h2>
+  <div class="card-grid">
+    <a class="doc-card" href="/en/whats-new">
+      <span class="card-kicker">Product update</span>
+      <h3>What’s new</h3>
+      <p>Runtime truth, task trajectories, recovery, helper policy, and fail-closed completion receipts — including what runs automatically and what is opt-in.</p>
+    </a>
+    <a class="doc-card" href="/en/quickstart">
+      <span class="card-kicker">Get started</span>
+      <h3>Quickstart</h3>
+      <p>Install, open a repository, onboard context, choose a profile and permission mode, run the first task, and verify before handoff.</p>
+    </a>
+    <a class="doc-card" href="/en/scope">
+      <span class="card-kicker">Get started</span>
+      <h3>Platform scope</h3>
+      <p>Why this repository exists alongside general coding agents, and which operating concerns it owns.</p>
+    </a>
+    <a class="doc-card" href="/en/profiles">
+      <span class="card-kicker">Build</span>
+      <h3>Project profiles</h3>
+      <p>Choose the operating profile for a repository: protected paths, verification commands, and granted capabilities.</p>
+    </a>
+    <a class="doc-card" href="/en/mcp">
+      <span class="card-kicker">MCP</span>
+      <h3>MCP</h3>
+      <p>Four configuration layers, pinned presets, server management, authentication readiness, and repository approval gates.</p>
+    </a>
+    <a class="doc-card" href="/en/security">
+      <span class="card-kicker">Operate</span>
+      <h3>Security model</h3>
+      <p>A policy enforcement layer, not an OS sandbox, with explicit claims about what is and is not controlled.</p>
+    </a>
+    <a class="doc-card" href="/en/benchmark">
+      <span class="card-kicker">Operate</span>
+      <h3>Production benchmark</h3>
+      <p>Quality, safety, workflow, and token evidence from 108 sessions compared with the <code>codex-cli</code> surface.</p>
+    </a>
+    <a class="doc-card" href="/en/commands">
+      <span class="card-kicker">Build</span>
+      <h3>Command catalog</h3>
+      <p>Slash commands and terminal commands grouped by the job they perform.</p>
+    </a>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="doc-groups">Three documentation groups</h2>
+  <div class="split">
+    <div class="card">
+      <h3 id="get-started-group">Get started</h3>
+      <p>For first-time users: installation, quickstart, and where the platform fits alongside other agent CLIs.</p>
+    </div>
+    <div class="card">
+      <h3 id="build-group">Build</h3>
+      <p>Daily operation: profiles, permissions, commands, workflows, and a dedicated MCP section for its broader command surface.</p>
+    </div>
+    <div class="card">
+      <h3 id="operate-group">Operate</h3>
+      <p>For operators and reviewers: security boundaries, repository architecture, terminal tools, and the team operating standard.</p>
+    </div>
+  </div>
+</section>

package/docs-site/content/en/mcp-approval.html

@@ -0,0 +1,74 @@
+<section class="section">
+  <h2 id="problem">The problem</h2>
+  <p>A repository may include <span class="inline-code">.mcp.json</span> and <span class="inline-code">.pi/mcp.json</span>. Cloning an untrusted repository and opening a session must <strong>not</strong> grant its author a process on the operator's machine with the operator's credentials. Servers from those scopes remain unavailable until someone on the machine approves them.</p>
+  <pre><code>/piagent-mcp get internal        # inspect first
+/piagent-mcp approve internal    # or reject, or reset</code></pre>
+  <p>In a terminal, omit the slash: <span class="inline-code">piagent-mcp get internal</span>. Both surfaces store the same decision in the same file.</p>
+  <p><span class="inline-code">approve</span> prints the definition before recording consent. Approving without reading is exactly what this gate is designed to prevent.</p>
+</section>
+
+<section class="section">
+  <h2 id="three-properties">Three properties</h2>
+  <div class="grid">
+    <div class="card"><h3 id="outside-repository">The decision lives outside the repository</h3><p>It is stored in <span class="inline-code">~/.pi/piagent-mcp-approvals.json</span>. If a repository could approve itself, the gate would not exist. A fork, rename, or second checkout starts at <span class="inline-code">pending</span>.</p></div>
+    <div class="card"><h3 id="digest-pinning">Pinned by digest</h3><p>Approval means consenting to <em>what the server runs</em>. Changing the command, URL, or arguments creates a new decision and returns the state to <span class="inline-code">approval-changed</span>.</p></div>
+    <div class="card"><h3 id="tool-call-enforcement">Enforced at tool call</h3><p>The guard handles both the proxy form (<span class="inline-code">mcp</span> with <span class="inline-code">input.server</span>) and direct tools. A proxy-only gate could be bypassed by enabling <span class="inline-code">directTools</span>.</p></div>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="limit">Limit</h2>
+  <div class="callout">
+    <strong>The gate cannot prevent connection establishment</strong>
+    <p>The adapter owns connections, so the extension cannot stop one from opening. It blocks <strong>every tool call</strong>, not the connection itself. The residual risk is the connection and any remote log that records it.</p>
+  </div>
+  <p>Servers in <span class="inline-code">global</span> and <span class="inline-code">pi-global</span> do not pass through this gate. A repository cannot place a server in those scopes, and asking users to approve their own machine configuration would add no security value.</p>
+</section>
+
+<section class="section">
+  <h2 id="imports">Servers supplied through <span class="inline-code">imports</span></h2>
+  <p>MCP configuration supports an <span class="inline-code">imports</span> key that reads server definitions from other tools. Imported servers are not directly declared in one of the four scopes, which creates another path around a naive approval gate.</p>
+  <p>Of the six import kinds, only <span class="inline-code">vscode</span> points to a path <strong>inside the project</strong>: <span class="inline-code">.vscode/mcp.json</span>. It travels with a clone and requires approval like any directly declared repository server.</p>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Situation</th><th>Handling</th></tr></thead>
+      <tbody>
+        <tr><td>Any layer imports a repository-relative kind</td><td>The server requires approval even when the import is declared globally, because the loaded content still lives in the repository.</td></tr>
+        <tr><td>A repository scope imports any kind</td><td>The server requires approval because the repository selected what the machine should run.</td></tr>
+        <tr><td>A repository scope imports a format that cannot be read, such as Codex TOML</td><td>Block every tool call when that file exists. A present but unreadable source is not equivalent to an empty configuration.</td></tr>
+        <tr><td><span class="inline-code">remove</span>, <span class="inline-code">enable</span>, or <span class="inline-code">disable</span> targets an imported server</td><td>Reject the operation and name the actual file to edit. Rewriting another tool's configuration with the platform writer would corrupt ownership and format.</td></tr>
+        <tr><td>Repository configuration combines <span class="inline-code">directTools</span> with <span class="inline-code">toolPrefix: "none"</span></td><td>Block every tool call. Without a prefix, the server identity cannot be recovered for approval lookup, while blocking only the proxy would let the unprefixed direct tools pass.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <p><span class="inline-code">piagent-mcp doctor</span> names the importing file, its import kinds, unreadable layers, and import targets that exist but cannot be read. These states must not collapse into "no servers declared".</p>
+  <p>For full-block states, <span class="inline-code">doctor</span> and <span class="inline-code">list</span> explain the reason and exit 1, including <span class="inline-code">list --json</span>. Exit status answers whether MCP can operate, not whether the command printed rows. The guard, slash command, and CLI consume the same state.</p>
+  <p>The gate cache is scoped by project and recomputed when the signature of every file used by readers changes, including currently missing paths. This lets a newly created imported file or a personal global change become visible immediately.</p>
+  <p>The adapter merges <span class="inline-code">settings</span> across all four layers for the session. Therefore <span class="inline-code">directTools</span> in one file and <span class="inline-code">toolPrefix: "none"</span> in another still form the unsafe combination. The report identifies both files.</p>
+  <p>The <span class="inline-code">SCOPE</span> column names the layer that declared <span class="inline-code">imports</span>, not the location that defined the server. A server imported by global configuration may still require approval when its source is in the clone.</p>
+</section>
+
+<section class="section">
+  <h2 id="design-decisions">Design decisions</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Decision</th><th>Reason</th></tr></thead>
+      <tbody>
+        <tr><td>Gate repository-supplied servers only</td><td>Only <span class="inline-code">.mcp.json</span> and <span class="inline-code">.pi/mcp.json</span> travel with a clone. User-owned machine configuration needs no repository consent.</td></tr>
+        <tr><td>Store decisions outside the repository</td><td><span class="inline-code">~/.pi/piagent-mcp-approvals.json</span> prevents a repository from approving itself.</td></tr>
+        <tr><td>Pin the definition digest</td><td>Consent applies to the exact command, arguments, and URL. A change returns the server to pending.</td></tr>
+        <tr><td>Preview the merged definition but hash the repository-owned fragment</td><td>The adapter merges duplicate IDs by key, so preview must show what will run. Hashing only the repository-controlled fragment prevents unrelated global edits from invalidating consent.</td></tr>
+        <tr><td>Block at <span class="inline-code">tool_call</span></td><td>Cover both proxy and direct tools without a bypass. Direct tools are traced through their configured server prefix.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <p>The ideal point would be before connection, but that requires owning the connection. Piagent chooses the furthest point it actually controls and states the residual risk explicitly.</p>
+</section>
+
+<section class="section">
+  <h2 id="migration">Migration</h2>
+  <div class="callout">
+    <strong>Projects with existing servers</strong>
+    <p>Servers already present in <span class="inline-code">.mcp.json</span> or <span class="inline-code">.pi/mcp.json</span> become <span class="inline-code">pending-approval</span> after update. Run <span class="inline-code">/piagent-mcp approve &lt;name&gt;</span> once per project. Shipped templates are empty, so most projects are unaffected; session notices and doctor name every server requiring review.</p>
+  </div>
+</section>

package/docs-site/content/en/mcp-auth.html

@@ -0,0 +1,57 @@
+<section class="section">
+  <h2 id="no-token-storage">The platform does not store tokens</h2>
+  <p>MCP tokens already have an owner: OAuth belongs to <span class="inline-code">pi-mcp-adapter</span>. The adapter registers <span class="inline-code">/mcp</span> and <span class="inline-code">/mcp-auth</span> and owns storage, refresh, and revocation. A second credential store would only create another leak surface. The platform therefore <strong>detects and guides</strong>.</p>
+  <pre><code>/mcp-auth figma</code></pre>
+  <div class="callout ok-callout">
+    <strong>Boundary</strong>
+    <p>The platform does not execute OAuth, store tokens, or refresh them. It can identify that a server <em>requires</em> authentication, but cannot prove whether an existing login is still valid, and reports that uncertainty explicitly.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="reject-secrets">Secrets are rejected before configuration is written</h2>
+  <p>MCP configuration may be read by several clients, lives in a home directory or repository, and project scope may be committed. A token supplied through <span class="inline-code">--env</span> would propagate to all those locations. The add command rejects it and shows the safe form:</p>
+  <pre><code>$ piagent-mcp add gh --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @acme/gh-mcp
+FAIL: GITHUB_PERSONAL_ACCESS_TOKEN names a credential, so its value cannot be
+written into MCP config. Export it in your shell and reference it instead:
+--env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}'</code></pre>
+  <div class="split">
+    <div class="card"><h3 id="field-name">Field-name detection</h3><p>Names containing <span class="inline-code">token</span>, <span class="inline-code">secret</span>, <span class="inline-code">password</span>, <span class="inline-code">api_key</span>, or <span class="inline-code">authorization</span> require environment-variable references.</p></div>
+    <div class="card"><h3 id="value-shape">Value-shape detection</h3><p>Values are checked independently, so a neutral name such as <span class="inline-code">--env CONFIG=ghp_...</span> is also rejected.</p></div>
+  </div>
+  <p>The same rules apply to <span class="inline-code">--header</span>. <span class="inline-code">--url</span> accepts HTTPS, or HTTP only for loopback hosts such as Figma desktop MCP. <span class="inline-code">list</span> and <span class="inline-code">get</span> mask values while preserving <span class="inline-code">${VAR}</span>, because the variable name is not the credential.</p>
+</section>
+
+<section class="section">
+  <h2 id="readiness">Readiness states</h2>
+  <p>A server count cannot show which server can answer a call. <span class="inline-code">/piagent-mcp doctor</span> classifies each server:</p>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>State</th><th>Meaning</th><th>Action</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">ready</span></td><td>Requirements are satisfied</td><td>—</td></tr>
+        <tr><td><span class="inline-code">needs-env</span></td><td>Configuration references an unset <span class="inline-code">${VAR}</span></td><td>Export the variable in the shell profile</td></tr>
+        <tr><td><span class="inline-code">needs-command</span></td><td>The executable is missing from PATH</td><td>Install it or update the server definition</td></tr>
+        <tr><td><span class="inline-code">pending-approval</span></td><td>The repository supplied this server and the machine has not approved it</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td></tr>
+        <tr><td><span class="inline-code">approval-changed</span></td><td>An approved definition changed</td><td>Review and approve again</td></tr>
+        <tr><td><span class="inline-code">rejected</span></td><td>The project server was rejected</td><td>Use <span class="inline-code">reset</span> to reconsider</td></tr>
+        <tr><td><span class="inline-code">disabled</span></td><td>Disabled explicitly</td><td><span class="inline-code">/piagent-mcp enable &lt;name&gt;</span></td></tr>
+        <tr><td><span class="inline-code">oauth</span></td><td>Authentication is owned by Pi</td><td><span class="inline-code">/mcp-auth &lt;name&gt;</span> when login is needed</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <p>The report states only what it can prove. <span class="inline-code">needs-env</span> prints the variable <strong>name</strong>, never its value.</p>
+  <p>Inside a session, <span class="inline-code">/piagent-mcp doctor</span> returns the same report with slash-command remedies. From a terminal:</p>
+  <pre><code>$ piagent-mcp doctor
+OK   context7 (global): ready
+OK   chrome-devtools (global): ready
+NEED github (global): GITHUB_PERSONAL_ACCESS_TOKEN is referenced but not set
+       -> export GITHUB_PERSONAL_ACCESS_TOKEN=... in your shell profile
+NEED docker: installed but the daemon is not responding
+       -> start Docker Desktop, then re-run piagent-mcp doctor</code></pre>
+  <div class="callout">
+    <strong>Why <span class="inline-code">oauth</span> is not an error</strong>
+    <p>It does not appear in the session-start notice because the platform cannot tell whether the user is already logged in. Repeating an uncertain warning every session would create noise. The notice includes only proven blockers; disable it with <span class="inline-code">PIAGENT_NO_MCP_NOTICE=1</span>.</p>
+  </div>
+  <p><span class="inline-code">doctor</span> also runs <span class="inline-code">docker info</span>. That slower check belongs in doctor, not session startup. <span class="inline-code">piagent-doctor</span> includes blocking states in its warnings.</p>
+</section>