@piagent/platform 1.2.15 → 1.2.17

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

@@ -0,0 +1,164 @@
+<section class="benchmark-summary" aria-labelledby="benchmark-verdict">
+  <div class="benchmark-verdict">
+    <div>
+      <p class="section-kicker">Production V1 · release 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">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 synthetic production benchmark built by the maintainer, not an independent benchmark proving that Piagent is better for every repository or model. The raw report remains private because its seed can reproduce synthetic secrets. Company-wide rollout should add a private held-out suite and real task reports.</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,39 @@
+<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-orchestration</span><span class="tag">/usage</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>

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,85 @@
+<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/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/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>

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

@@ -0,0 +1,91 @@
+<section class="section">
+  <h2 id="two-surfaces">Two surfaces for two contexts</h2>
+  <p>Inside a Pi session, use the <strong>slash command</strong>. In a terminal, use the <strong>CLI</strong>. Both read the same state; the difference is where the operation runs.</p>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Task</th><th>In a session</th><th>In a terminal</th></tr></thead>
+      <tbody>
+        <tr><td>Open the menu</td><td><span class="inline-code">/piagent-mcp</span></td><td>—</td></tr>
+        <tr><td>List servers and state</td><td><span class="inline-code">/piagent-mcp status</span></td><td><span class="inline-code">piagent-mcp list</span></td></tr>
+        <tr><td>Inspect one server</td><td><span class="inline-code">/piagent-mcp get &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp get &lt;name&gt;</span></td></tr>
+        <tr><td>Show readiness blockers</td><td><span class="inline-code">/piagent-mcp doctor</span></td><td><span class="inline-code">piagent-mcp doctor</span></td></tr>
+        <tr><td>Approve a repository server</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp approve &lt;name&gt;</span></td></tr>
+        <tr><td>Enable or disable</td><td><span class="inline-code">/piagent-mcp enable|disable &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp enable|disable &lt;name&gt;</span></td></tr>
+        <tr><td>Add, remove, or seed a preset</td><td>—</td><td><span class="inline-code">piagent-mcp add|remove|--preset</span></td></tr>
+        <tr><td>Live connection state or OAuth</td><td><span class="inline-code">/mcp</span>, <span class="inline-code">/mcp-auth</span></td><td>—</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout ok-callout">
+    <strong>Why use a slash command instead of invoking the CLI in-session</strong>
+    <p>Asking the model to run <span class="inline-code">piagent-mcp list</span> through bash spends model turns executing, reading, and restating data that the current process already has. Pi dispatches the slash command directly to its handler: no model tokens, no interpretation, and a deterministic response.</p>
+  </div>
+  <div class="callout">
+    <strong>Adding a server remains terminal-only</strong>
+    <p><span class="inline-code">add</span> includes shell quoting, <span class="inline-code">${VAR}</span> references, and a command line after <span class="inline-code">--</span>. The shell already parses these correctly. Reimplementing that parser in a slash command would create a second, weaker grammar. <span class="inline-code">/piagent-mcp add</span> prints the exact terminal command to run.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="commands">Commands</h2>
+  <div class="command-grid">
+    <article class="command-card">
+      <h3 id="in-session">In a session</h3>
+      <p>No arguments opens the menu. Direct commands support Tab completion for subcommands and server names.</p>
+      <pre><code>/piagent-mcp                 menu
+/piagent-mcp status          full table
+/piagent-mcp get sentry
+/piagent-mcp doctor
+/piagent-mcp approve internal</code></pre>
+    </article>
+    <article class="command-card">
+      <h3 id="add-server">Add a server</h3>
+      <p>Use <span class="inline-code">--url</span> for a remote server, or place a local server command after <span class="inline-code">--</span>. Run this in a terminal.</p>
+      <pre><code>piagent-mcp add sentry --url https://mcp.sentry.dev/mcp --scope global
+piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp</code></pre>
+    </article>
+    <article class="command-card">
+      <h3 id="inspect">Inspect</h3>
+      <p><span class="inline-code">list</span> shows every server visible from the current project and its state. <span class="inline-code">get</span> shows one server in detail.</p>
+      <pre><code>piagent-mcp list
+piagent-mcp get sentry</code></pre>
+    </article>
+    <article class="command-card">
+      <h3 id="disable-remove">Disable and remove</h3>
+      <p><span class="inline-code">disable</span> preserves the definition but stops using it. <span class="inline-code">remove</span> deletes it from a scope.</p>
+      <pre><code>piagent-mcp disable sentry
+piagent-mcp enable sentry
+piagent-mcp remove sentry --scope global</code></pre>
+    </article>
+    <article class="command-card">
+      <h3 id="preset-command">Preset</h3>
+      <p>Seed a pinned group of servers. <span class="inline-code">--replace</span> returns preset-owned servers to their baseline.</p>
+      <pre><code>piagent-mcp --preset core --scope global --replace
+piagent-mcp --list</code></pre>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="output">Output names the modified file</h2>
+  <p>All four configuration layers are read, so the first debugging question is which file is active. <span class="inline-code">add</span> answers that directly:</p>
+  <pre><code>$ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp
+Added local MCP server internal with command: npx -y @acme/internal-mcp in project scope
+File modified: /Users/you/repo/.mcp.json
+This scope is part of the repository, so the server is not usable until approved: piagent-mcp approve internal</code></pre>
+  <p><span class="inline-code">list</span> renders a table whose <span class="inline-code">STATE</span> column identifies immediately usable servers:</p>
+  <pre><code>NAME             SCOPE    TRANSPORT  TARGET                                  STATE
+context7         global   stdio      npx -y @upstash/context7-mcp@3.2.4       ready
+chrome-devtools  global   stdio      npx -y chrome-devtools-mcp@1.6.0 ...     ready
+github           global   stdio      docker run -i --rm -e GITHUB_PERSON...   needs-env
+internal         project  stdio      npx -y @acme/internal-mcp               pending-approval</code></pre>
+</section>
+
+<section class="section">
+  <h2 id="updates">Custom servers and updates</h2>
+  <p>Each <span class="inline-code">piagent-update</span> reapplies the selected preset with <span class="inline-code">--replace</span>. The merge touches only server IDs owned by that preset.</p>
+  <div class="split">
+    <div class="card"><h3 id="preserved">Preserved</h3><p>Custom IDs such as <span class="inline-code">my-internal</span> or <span class="inline-code">sentry</span> survive every update.</p></div>
+    <div class="card"><h3 id="overwritten">Replaced</h3><p>Manual edits to preset-owned IDs such as <span class="inline-code">github</span> or <span class="inline-code">context7</span> return to baseline on the next update. Use a distinct ID for a custom variant.</p></div>
+  </div>
+</section>