@piagent/platform 1.2.16 → 1.3.0-ie.8

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>

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

@@ -0,0 +1,90 @@
+<section class="section">
+  <h2 id="start">Where to start</h2>
+  <p>Enter <span class="inline-code">/piagent-mcp</span> to open a menu. You do not need to memorize subcommands:</p>
+  <pre><code>MCP
+  Servers — 2/3 ready
+  Doctor — 1 need attention          (recommended)
+  Inspect a server
+  Approve a repository server — 1 waiting
+  Turn a server off
+  Add a server
+  All subcommands</code></pre>
+  <p>The menu reflects the current project. It does not offer "turn back on" when no server is disabled or "approve" when nothing is waiting. When an action requires a server, it asks which one unless only one choice exists.</p>
+  <p>Every menu item also has a direct command:</p>
+  <pre><code>/piagent-mcp doctor     show what is blocked and what it needs
+/piagent-mcp status     show the full table
+/mcp                    show live connection state from the adapter
+/mcp-auth &lt;name&gt;        authenticate one OAuth server</code></pre>
+  <p>In a terminal, use the same command family without the slash: <span class="inline-code">piagent-mcp list</span> or <span class="inline-code">piagent-mcp doctor</span>. Adding and removing server definitions is terminal-only. See <a href="/en/mcp-servers">Server management</a>.</p>
+</section>
+
+<section class="section">
+  <h2 id="three-similar-names">Three similar names that are not connected</h2>
+  <p>No code maps a capability name to an MCP server ID. Declaring <span class="inline-code">"github"</span> in <span class="inline-code">mcpCapabilities</span> does <strong>not</strong> enable the MCP server named <span class="inline-code">github</span>, and the reverse is also false.</p>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Item</th><th>Location</th><th>Meaning</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">mcpCapabilities: ["github"]</span></td><td><span class="inline-code">.pi/piagent-profile.json</span></td><td>A capability label for the tool registry</td></tr>
+        <tr><td><span class="inline-code">toolCapabilities</span></td><td><span class="inline-code">base-policy.json</span></td><td>Maps a tool <strong>named</strong> <span class="inline-code">github</span> to a capability</td></tr>
+        <tr><td><span class="inline-code">github</span> server</td><td><span class="inline-code">~/.config/mcp/mcp.json</span></td><td>The actual MCP server, running through Docker</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="four-config-layers">Four configuration layers</h2>
+  <p>All four files are read. The <span class="inline-code">--scope</span> option of <span class="inline-code">piagent-mcp</span> uses these names.</p>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Scope</th><th>File</th><th>Use</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">global</span></td><td><span class="inline-code">~/.config/mcp/mcp.json</span></td><td>Default shared configuration for multiple agents and projects</td></tr>
+        <tr><td><span class="inline-code">pi-global</span></td><td><span class="inline-code">~/.pi/agent/mcp.json</span></td><td>Pi-specific global overrides</td></tr>
+        <tr><td><span class="inline-code">project</span></td><td><span class="inline-code">.mcp.json</span></td><td>Repository-specific, committable server definitions</td></tr>
+        <tr><td><span class="inline-code">pi-project</span></td><td><span class="inline-code">.pi/mcp.json</span></td><td>Pi-specific overrides for one repository</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>The final two layers travel with the repository</strong>
+    <p>Cloning a repository also brings its <span class="inline-code">.mcp.json</span>. Servers from these scopes must pass the <a href="/en/mcp-approval">approval gate</a> before use.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="presets">Pinned presets</h2>
+  <p><span class="inline-code">piagent-setup</span> and <span class="inline-code">piagent-install</span> install <span class="inline-code">pi-mcp-adapter</span> and seed the <span class="inline-code">core</span> preset by default. Skip this with <span class="inline-code">--no-mcp</span>.</p>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Preset</th><th>Servers</th><th>Purpose</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">minimal</span></td><td>—</td><td>Safe settings only</td></tr>
+        <tr><td><span class="inline-code">docs</span></td><td>Context7</td><td>Current framework and library docs</td></tr>
+        <tr><td><span class="inline-code">browser</span></td><td>Chrome DevTools, Playwright</td><td>UI/runtime inspection and browser automation</td></tr>
+        <tr><td><span class="inline-code">github</span></td><td>GitHub MCP</td><td>Issue, PR, repository, and release workflows</td></tr>
+        <tr><td><span class="inline-code">design</span></td><td>Figma remote</td><td>Design-to-code through Figma OAuth</td></tr>
+        <tr><td><span class="inline-code">design-local</span></td><td>Figma desktop</td><td>Local Dev Mode MCP</td></tr>
+        <tr><td><span class="inline-code">web</span></td><td>Context7, Chrome DevTools, Playwright</td><td>Frontend and web workflows</td></tr>
+        <tr><td><span class="inline-code">core</span></td><td>Context7, Chrome DevTools, GitHub</td><td>Default team baseline</td></tr>
+        <tr><td><span class="inline-code">popular</span></td><td>core + Playwright + Figma</td><td>A broader development baseline</td></tr>
+        <tr><td><span class="inline-code">all</span></td><td>popular + Figma desktop</td><td>Complete preset</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <p>Every server is pinned by version or digest. An MCP server is code running on the operator's machine with the operator's credentials, so floating tags would turn each session into an unattended supply-chain decision.</p>
+  <div class="callout">
+    <strong>Writing configuration does not prove readiness</strong>
+    <p>Servers connect lazily and are not checked until first use. <a href="/en/mcp-auth">Authentication and readiness</a> explains which servers can actually run.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="token-efficiency">Token efficiency</h2>
+  <p><span class="inline-code">pi-mcp-adapter</span> exposes all servers through one proxy tool named <span class="inline-code">mcp</span> instead of loading every tool schema into startup context. Defaults include <span class="inline-code">directTools: false</span>, <span class="inline-code">outputGuard</span>, and <span class="inline-code">idleTimeout</span>.</p>
+  <div class="callout">
+    <strong>Warning when enabling <span class="inline-code">toolRegistry: enforce</span></strong>
+    <p>The proxy tool <span class="inline-code">mcp</span> is not in <span class="inline-code">alwaysAllowedTools</span> or <span class="inline-code">toolCapabilities</span>, so enforce mode blocks <strong>all</strong> MCP access. Adding <span class="inline-code">mcpCapabilities</span> cannot bypass that earlier block. The only exception is <span class="inline-code">trusted-full-access</span>.</p>
+  </div>
+</section>

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

@@ -0,0 +1,19 @@
+<section class="section">
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Mode</th><th>Use it for</th><th>Boundary</th><th>Command</th></tr></thead>
+      <tbody>
+        <tr><td><span class="inline-code">read-only</span></td><td>Scouting, audits, mapping, and reviews without source edits.</td><td>Allows read, grep, find, ls, and Piagent tools; blocks shell, write, and unknown tools.</td><td><span class="inline-code">/permission read-only</span></td></tr>
+        <tr><td><span class="inline-code">workspace-write</span></td><td>Normal implementation inside the repository.</td><td>Default guarded mode with protected paths, shell policy, capabilities, and verification gates.</td><td><span class="inline-code">/permission workspace-write</span></td></tr>
+        <tr><td><span class="inline-code">trusted-full-access</span></td><td>Automation in a trusted repository with a clearly bounded task.</td><td>Expands autonomy while retaining protected paths, redaction, integrity locks, and confirmation gates.</td><td><span class="inline-code">/permission full-access</span></td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <div class="command-grid">
+    <article class="command-card"><header><span>Show permission</span><button class="clip-btn" data-clip="/permission status">Copy</button></header><pre><code>/permission status</code></pre></article>
+    <article class="command-card"><header><span>Read-only session</span><button class="clip-btn" data-clip="/permission read-only">Copy</button></header><pre><code>/permission read-only</code></pre></article>
+    <article class="command-card"><header><span>Workspace write</span><button class="clip-btn" data-clip="/permission workspace-write">Copy</button></header><pre><code>/permission workspace-write</code></pre></article>
+    <article class="command-card"><header><span>Full access with a task</span><button class="clip-btn" data-clip="/permission full-access Run the trusted local verification suite.">Copy</button></header><pre><code>/permission full-access Run the trusted local verification suite.</code></pre></article>
+  </div>
+</section>

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

@@ -0,0 +1,27 @@
+<section class="section">
+  <div class="command-grid">
+    <article class="command-card"><header><span>Show concise status</span><button class="clip-btn" data-clip="/profile">Copy</button></header><pre><code>/profile</code></pre></article>
+    <article class="command-card"><header><span>List options</span><button class="clip-btn" data-clip="/profile list">Copy</button></header><pre><code>/profile list</code></pre></article>
+    <article class="command-card"><header><span>Apply detected profile</span><button class="clip-btn" data-clip="/profile auto">Copy</button></header><pre><code>/profile auto</code></pre></article>
+    <article class="command-card"><header><span>Interactive setup</span><button class="clip-btn" data-clip="/profile setup&#10;/profile tech setup fullstack">Copy</button></header><pre><code>/profile setup
+/profile tech setup fullstack</code></pre></article>
+    <article class="command-card"><header><span>Deterministic tech selection</span><button class="clip-btn" data-clip="/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma">Copy</button></header><pre><code>/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma</code></pre></article>
+    <article class="command-card"><header><span>Frontend</span><button class="clip-btn" data-clip="/profile web-frontend">Copy</button></header><pre><code>/profile web-frontend
+/profile fe</code></pre></article>
+    <article class="command-card"><header><span>Backend/API</span><button class="clip-btn" data-clip="/profile backend-api">Copy</button></header><pre><code>/profile backend-api</code></pre></article>
+    <article class="command-card"><header><span>Read-only backend, writable frontend</span><button class="clip-btn" data-clip="/profile be-readonly-fe">Copy</button></header><pre><code>/profile be-readonly-fe
+/profile be-fe</code></pre></article>
+    <article class="command-card"><header><span>Full stack</span><button class="clip-btn" data-clip="/profile fullstack">Copy</button></header><pre><code>/profile fullstack
+/profile full</code></pre></article>
+    <article class="command-card"><header><span>Docs only</span><button class="clip-btn" data-clip="/profile docs">Copy</button></header><pre><code>/profile docs</code></pre></article>
+  </div>
+
+  <div class="tag-list">
+    <span class="tag">generic</span><span class="tag">node-typescript</span><span class="tag">python</span><span class="tag">web-frontend</span><span class="tag">backend-api</span><span class="tag">fullstack</span><span class="tag">be-readonly-fe</span><span class="tag">data</span><span class="tag">devops</span><span class="tag">mobile</span><span class="tag">docs</span>
+  </div>
+
+  <div class="callout">
+    <strong>Technology stack by role</strong>
+    <p>Frontend profiles select frontend technology and an optional database; backend profiles select backend technology and an optional database; full-stack profiles select frontend, backend, and database. The platform then writes <span class="inline-code">.pi/tech-stack.json</span> and a compact Context7 snapshot under <span class="inline-code">.pi/tech-context/*</span>.</p>
+  </div>
+</section>

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

@@ -0,0 +1,126 @@
+<section class="section">
+  <div class="steps">
+    <article class="step">
+      <div>
+        <h3 id="install-two-commands">Install with two commands</h3>
+        <p>Requires Node.js 22.19.0 or newer. You do not need to install Pi Coding Agent first: <span class="inline-code">piagent-setup</span> installs the exact host version pinned by the current release. Run it inside the project directory. It installs the Pi package, initializes <span class="inline-code">.pi/</span>, installs the MCP baseline and subagents, and runs doctor. Use <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span>, or <span class="inline-code">--global-only</span> to omit optional parts.</p>
+        <div class="table-wrap compact-table">
+          <table>
+            <thead><tr><th>Runtime</th><th>Rollout status</th></tr></thead>
+            <tbody>
+              <tr><td>macOS Apple Silicon + Bash</td><td>Verified for this release.</td></tr>
+              <tr><td>Linux x64 + Bash</td><td>Verified in CI.</td></tr>
+              <tr><td>macOS Intel / Linux ARM64 + Bash</td><td>Supported target; run doctor and smoke tests before broad rollout.</td></tr>
+              <tr><td>Native Windows / WSL2</td><td>Not a team rollout target; WSL2 remains experimental.</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <div class="command-card">
+          <header><span>Two commands</span><button class="clip-btn" data-clip="npm install -g @piagent/platform&#10;piagent-setup">Copy</button></header>
+          <pre><code>npm install -g @piagent/platform
+piagent-setup</code></pre>
+        </div>
+        <p>Because setup runs from the installed package, the source written to <span class="inline-code">.pi/settings.json</span> is <span class="inline-code">npm:@piagent/platform@&lt;version&gt;</span>. It resolves consistently on teammate machines and can be committed.</p>
+        <p>If you use <a href="https://herdr.dev/docs/install/">Herdr</a>, install it <strong>first</strong>. <span class="inline-code">piagent-setup</span> installs the Herdr Pi integration when <span class="inline-code">herdr</span> is present on <span class="inline-code">PATH</span>. Otherwise it skips the integration with a warning; after installing Herdr, run <span class="inline-code">piagent-setup --global-only</span>.</p>
+        <div class="command-card">
+          <header><span>Herdr (optional, install first)</span><button class="clip-btn" data-clip="brew install herdr">Copy</button></header>
+          <pre><code>brew install herdr                            # macOS
+curl -fsSL https://herdr.dev/install.sh | sh  # macOS or Linux</code></pre>
+        </div>
+        <p>The <span class="inline-code">curl</span> form executes a downloaded installer. For an auditable path, use <span class="inline-code">brew</span> or download from <a href="https://github.com/ogulcancelik/herdr/releases">GitHub releases</a>. Herdr stable supports macOS and Linux; Windows remains preview.</p>
+        <p>See the <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/release-install-policy.md">release and install policy</a> for pinned rollout, updates, rollback, and the latest channel for personal machines.</p>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="open-project-repository">Open the project repository</h3>
+        <p>Start Pi from the repository directory. In a trusted repository, use the trusted-run wrapper only when controlled automation is needed.</p>
+        <div class="command-card">
+          <header><span>Start</span><button class="clip-btn" data-clip="cd /path/to/project && pi">Copy</button></header>
+          <pre><code>cd /path/to/project
+pi</code></pre>
+        </div>
+        <p>For multiple parallel agents, run <span class="inline-code">herdr</span> instead of <span class="inline-code">pi</span> and assign one role per pane: implementation, read-only review, verification, or notes. Herdr coordinates terminals and sessions; it is not a security boundary. Gates remain in the Pi extension and OAuth still occurs in Pi. See the <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/herdr-workflow.md">Herdr workflow</a>.</p>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="onboard-context">Onboard context</h3>
+        <p>Run this once in a new repository to record project context, verification matrices, and protected areas under <span class="inline-code">.pi/</span>. <span class="inline-code">/onboard</span> opens the menu and status; <span class="inline-code">run</span> launches the project-reading workflow.</p>
+        <div class="command-card">
+          <header><span>Onboard</span><button class="clip-btn" data-clip="/onboard&#10;/onboard run">Copy</button></header>
+          <pre><code>/onboard
+/onboard run</code></pre>
+        </div>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="select-profile-and-tech">Select profile and technology</h3>
+        <p>Use <span class="inline-code">/profile setup</span> for the interactive selector: choose the profile, then the technology by role. Full-stack setup selects frontend, backend, and database.</p>
+        <div class="command-card">
+          <header><span>Profile and tech setup</span><button class="clip-btn" data-clip="/profile setup&#10;/profile tech setup fullstack">Copy</button></header>
+          <pre><code>/profile setup
+/profile tech setup fullstack</code></pre>
+        </div>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="select-permission">Select a permission mode</h3>
+        <p>Use read-only for scouting, workspace-write for normal coding, and guarded full access for trusted automation.</p>
+        <div class="command-card">
+          <header><span>Permission</span><button class="clip-btn" data-clip="/permission status&#10;/permission workspace-write">Copy</button></header>
+          <pre><code>/permission status
+/permission workspace-write</code></pre>
+        </div>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="run-workflow">Run a workflow</h3>
+        <p>Use the command that matches the intent so the agent does not spend context rediscovering the process. Start a fresh session for context-heavy work.</p>
+        <div class="command-card">
+          <header><span>Workflow</span><button class="clip-btn" data-clip="/workflow task Implement the requested bounded change.&#10;/workflow review current diff&#10;/fresh task Implement the requested bounded change.">Copy</button></header>
+          <pre><code>/workflow task Implement the requested bounded change.
+/workflow review current diff
+/fresh task Implement the requested bounded change.</code></pre>
+        </div>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="verify-before-handoff">Verify before handoff</h3>
+        <p>The final gate trusts only commands that actually ran, exited successfully, and matched the verification plan. After pinning or upgrading a version, run doctor in the project:</p>
+        <div class="command-card">
+          <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor">Copy</button></header>
+          <pre><code>piagent-doctor</code></pre>
+        </div>
+        <p>Platform maintainers also run <span class="inline-code">npm run verify</span> in the source repository. See <a href="https://github.com/Vt-mmm/piagent/blob/main/CONTRIBUTING.md">CONTRIBUTING</a>.</p>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="uninstall">Uninstall when no longer needed</h3>
+        <p><span class="inline-code">piagent-uninstall</span> is a dry run by default. Add <span class="inline-code">--apply</span> to make changes because it edits Pi settings that other tools may also use. The default removes only the platform's Pi package; add-ons, the Pi host, and project state are opt-in.</p>
+        <div class="command-card">
+          <header><span>Uninstall in two steps</span><button class="clip-btn" data-clip="piagent-uninstall&#10;piagent-uninstall --apply">Copy</button></header>
+          <pre><code>piagent-uninstall
+piagent-uninstall --apply</code></pre>
+        </div>
+        <p>Add-ons, the Pi host, project state, and the global npm helper each have separate opt-in flags listed by <span class="inline-code">piagent-uninstall --help</span>. Removal follows packages registered in Pi settings, so registrations created by older releases are still found.</p>
+        <div class="callout ok-callout">
+          <strong>Never removed</strong>
+          <p>Credentials, trust decisions, sessions, todos, and <span class="inline-code">.pi/memory/</span> remain under every flag combination. Generated files that may have been edited, such as <span class="inline-code">AGENTS.md</span>, <span class="inline-code">.pi/settings.json</span>, and <span class="inline-code">project-context.md</span>, are listed for manual review. In <span class="inline-code">.pi/settings.json</span>, only the package entry that points to the platform is removed.</p>
+        </div>
+      </div>
+    </article>
+  </div>
+</section>

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

@@ -0,0 +1,27 @@
+<section class="section">
+  <div class="command-grid">
+    <article class="command-card"><header><span>Global setup</span><button class="clip-btn" data-clip="piagent-setup --mcp-preset core --subagents-preset safe">Copy</button></header><pre><code>piagent-setup --mcp-preset core --subagents-preset safe</code></pre></article>
+    <article class="command-card"><header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Copy</button></header><pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
+piagent-install --stable --dry-run
+piagent-install --stable</code></pre></article>
+    <article class="command-card"><header><span>Pi package only</span><button class="clip-btn" data-clip="piagent-install --version vX.Y.Z --resolve-tag --dry-run&#10;piagent-install --version vX.Y.Z --resolve-tag">Copy</button></header><pre><code>piagent-install --version vX.Y.Z --resolve-tag --dry-run
+piagent-install --version vX.Y.Z --resolve-tag</code></pre></article>
+    <article class="command-card"><header><span>Initialize a project</span><button class="clip-btn" data-clip="piagent-init /path/to/project">Copy</button></header><pre><code>piagent-init /path/to/project</code></pre></article>
+    <article class="command-card"><header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor /path/to/project">Copy</button></header><pre><code>piagent-doctor /path/to/project</code></pre></article>
+    <article class="command-card"><header><span>Smoke benchmark</span><button class="clip-btn" data-clip="piagent-benchmark --dry-run&#10;piagent-benchmark">Copy</button></header><pre><code>piagent-benchmark --dry-run
+piagent-benchmark</code></pre></article>
+    <article class="command-card"><header><span>Production benchmark</span><button class="clip-btn" data-clip="piagent-benchmark --production --dry-run&#10;piagent-benchmark --production --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-sol --thinking xhigh">Copy</button></header><pre><code>piagent-benchmark --production --dry-run
+piagent-benchmark --production --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol --thinking xhigh</code></pre></article>
+    <article class="command-card"><header><span>Compare codex-cli</span><button class="clip-btn" data-clip="piagent-benchmark --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-sol --thinking xhigh">Copy</button></header><pre><code>piagent-benchmark --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol --thinking xhigh</code></pre></article>
+    <article class="command-card"><header><span>Trusted run</span><button class="clip-btn" data-clip="piagent-auto --full-access -p &quot;Run the trusted local benchmark suite.&quot;">Copy</button></header><pre><code>piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
+piagent-auto --full-access -p "Run the trusted local benchmark suite."</code></pre></article>
+    <article class="command-card"><header><span>Capabilities</span><button class="clip-btn" data-clip="piagent-capabilities catalog --check&#10;piagent-capabilities doctor --profile .pi/piagent-profile.json">Copy</button></header><pre><code>piagent-capabilities catalog --check
+piagent-capabilities doctor --profile .pi/piagent-profile.json</code></pre></article>
+    <article class="command-card"><header><span>Verification</span><button class="clip-btn" data-clip="npm run verify&#10;npm test&#10;npm run typecheck">Copy</button></header><pre><code>npm run verify
+npm test
+npm run typecheck</code></pre></article>
+  </div>
+</section>

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

@@ -0,0 +1,45 @@
+<section class="section">
+  <h2 id="not-a-new-agent">This is not a new agent</h2>
+  <p>The platform has no model, runtime, or agent loop of its own. It runs as a Pi extension and adds one thing: <strong>a repeatable operating model</strong> that every repository can reuse.</p>
+  <p>General coding agent CLIs already provide sandboxes, approvals, and project configuration. The useful question is not which agent is stronger. It is who configures those controls, and whether the configuration stays consistent across twenty repositories.</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Area</th><th>General agent CLI</th><th>What this platform adds</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>Role</td><td>A coding agent operating on a local repository with tool and command selection.</td><td>A governance layer for Pi: policy, profiles, and workflows represented as files instead of prompt conventions.</td></tr>
+        <tr><td>Team customization</td><td>Instructions, settings, permissions, hooks, skills, and MCP configured per repository.</td><td>Profile adapters, base policy, command guards, capability packs, docs, and scripts defined once and distributed with <span class="inline-code">piagent-init</span>.</td></tr>
+        <tr><td>Execution permissions</td><td>OS or process sandboxing, per-action approval, and workspace boundaries.</td><td>Three named modes: <span class="inline-code">read-only</span>, <span class="inline-code">workspace-write</span>, and <span class="inline-code">trusted-full-access</span>, changed with one command.</td></tr>
+        <tr><td>Secret safety</td><td>Sandbox, approval, and network policy beneath the tool layer.</td><td>Application-level policy after a tool call: protected paths, shell checks, symlink aliases, output redaction, and integrity locks.</td></tr>
+        <tr><td>Distinct value</td><td>A complete agent experience and broad tool ecosystem.</td><td>Repeatability: the same profiles, guard, and verification discipline across repositories, with differences visible in files.</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="complementary-layers">The two layers are complementary</h2>
+  <p>The host sandbox controls processes: a process cannot open files outside its permitted scope. The platform guard controls tool calls: it can inspect the <em>arguments</em> the agent intends to use, including paths, destinations, and external payloads.</p>
+  <div class="split">
+    <div class="card">
+      <h3 id="lower-layer">The lower layer sees processes</h3>
+      <p>It can tell that a process is writing outside the workspace. It cannot tell whether that process is <span class="inline-code">npm test</span> or a script generated during the current turn.</p>
+    </div>
+    <div class="card">
+      <h3 id="upper-layer">The upper layer sees intent</h3>
+      <p>It knows the tool, arguments, and capability. That is enough to block <span class="inline-code">.env</span> by name, redact tokens in output, and reject an MCP server supplied by a repository.</p>
+    </div>
+  </div>
+  <div class="callout">
+    <strong>Removing either layer leaves a gap</strong>
+    <p>An application guard cannot replace a sandbox once a process is running. A sandbox does not know why <span class="inline-code">.env</span> differs from <span class="inline-code">.env.example</span>. The platform assumes the lower layer remains enabled.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="when-not-needed">When you may not need it</h2>
+  <p>For one person, one repository, no meaningful secrets, and no shared operating process, Pi's native configuration may be sufficient.</p>
+  <p>The platform becomes useful when no one can remember which permissions are active across many repositories, or when "has this been verified?" needs the same evidence-based answer everywhere.</p>
+</section>

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

@@ -0,0 +1,33 @@
+<section class="section">
+  <div class="grid cols-2">
+    <article class="card"><h3 id="protected-paths">Protected paths</h3><p>Controlled tools block reads and writes to files such as <span class="inline-code">.env</span>, <span class="inline-code">auth.json</span>, local trust files, profile locks, and sensitive settings.</p></article>
+    <article class="card"><h3 id="shell-hardening">Shell hardening</h3><p>The guard uses shell parsing and controlled-command rules to catch globs, braces, redirects, bare-word symlinks, and xargs composition before runtime expansion.</p></article>
+    <article class="card"><h3 id="secret-redaction">Secret redaction</h3><p>Text tool output passes through a redactor for provider tokens, secret keyword patterns, and common sensitive values. Current benchmarks are synthetic and internal; the model continues to evolve.</p></article>
+    <article class="card"><h3 id="capability-lock">Capability lock</h3><p>Capability packs have digests and tamper detection. An invalid lock fails closed and never expands permissions automatically.</p></article>
+    <article class="card"><h3 id="human-action-gate">Human-action gate</h3><p>Destructive or external-provider actions require explicit operator confirmation even in full-access mode. The gate covers direct tools, decoded MCP proxy calls, GitHub CLI writes, and non-GET HTTP shell forms.</p></article>
+    <article class="card"><h3 id="verify-evidence">Verification evidence</h3><p>A completed handoff requires observed bash results, not an unsupported statement that tests passed.</p></article>
+  </div>
+
+  <div class="callout">
+    <strong>Important boundary</strong>
+    <p>The guard depends on controlled tool paths and the shell syntax it can observe. It cannot stop another process running with the same OS permissions outside the guard, and it does not replace operating-system sandboxing.</p>
+    <ul>
+      <li>Symlinks, encodings, nested payloads, shell expansion, or newly introduced tools can affect coverage.</li>
+      <li>Redaction is a leak-reduction backstop, not permission to place real secrets in prompts or outputs.</li>
+      <li>The context index is a local cache containing source bodies. Owner-only mode limits cross-account access, but processes under the same OS account must still be trusted.</li>
+      <li>Untrusted workloads require a container or VM with filesystem, process, network, and credential boundaries.</li>
+    </ul>
+  </div>
+
+  <div class="callout">
+    <strong>Redaction still requires independent audit</strong>
+    <p>Current benchmarks are synthetic internal regression and release gates, not an external security audit. The project publishes its <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/security-threat-model.md" target="_blank" rel="noopener noreferrer">threat model and attack-vector map</a>. Broader parser fuzzing, third-party review, and LTS guarantees remain higher assurance levels that are not currently claimed. Published npm packages do include signed provenance through GitHub Actions and Sigstore.</p>
+  </div>
+
+  <div class="callout">
+    <strong>Dependency gates separate two trees</strong>
+    <p>Releases audit the small terminal-helper dependency tree separately from the exact Pi host and pinned add-ons. The helper tree is clean. The current Pi host tree has one high and eleven moderate advisories; the project reports those numbers instead of claiming zero runtime vulnerabilities.</p>
+    <p>The high advisory is <span class="inline-code">GHSA-mh99-v99m-4gvg</span> in <span class="inline-code">brace-expansion</span>, a denial-of-service issue rather than privilege escalation or data exposure. The published Pi host shrinkwrap pins the affected version and overrides cannot replace it. The release gate exempts only this named advisory with a source-controlled rationale and expires the exemption on <span class="inline-code">2026-08-25</span> or when upstream publishes a fix. Every other high or critical advisory still blocks release.</p>
+    <p>The eleven moderate findings belong to two upstream advisories: encoded-backslash path traversal on Windows in a Hono adapter and a protobuf parser denial of service. Native Windows and WSL2 are not team rollout targets, but both findings remain tracked.</p>
+  </div>
+</section>

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

@@ -0,0 +1,14 @@
+<section class="section">
+  <div class="split">
+    <article class="card"><h3 id="do">Do</h3><p>Run <span class="inline-code">/onboard run</span>, apply <span class="inline-code">/profile auto</span>, use <span class="inline-code">/workflow</span>, execute real verification, and state blockers clearly.</p></article>
+    <article class="card"><h3 id="avoid">Avoid</h3><p>Do not place tokens, authentication files, caches, sessions, private examples, or project-specific business logic in the public core package.</p></article>
+  </div>
+  <div class="callout ok-callout">
+    <strong>Handoff standard</strong>
+    <p>A final response should briefly state what changed, which verification ran, whether subagents were used, and which risks or next steps require review.</p>
+  </div>
+  <div class="callout">
+    <strong>Release documentation gate</strong>
+    <p>A new docs version is promoted to Vercel only after tag-triggered CI passes and the stable dry run resolves the exact commit SHA. Promotion uses the tagged commit without an intervening merge or docs-only edit. The canonical domain is <span class="inline-code">piagent.io.vn</span>; the apex is the Vercel primary and <span class="inline-code">www</span> redirects to it.</p>
+  </div>
+</section>