@piagent/platform 1.41.0 → 1.42.1

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

@@ -1,124 +1,108 @@
 <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>Windows (WSL2)</td><td>One PowerShell command installs everything: see <a href="/en/windows">Windows</a>. Running on Windows itself is a preview of personal mode.</td></tr>
-            </tbody>
-          </table>
+      <h3 id="install">Install</h3>
+      <p>Requires Node.js 22.19.0 or later. You do not need Pi first: <code>piagent-setup</code> installs the exact Pi release this version pins, initializes <code>.pi/</code>, installs the MCP baseline and subagents, then runs the doctor.</p>
+      <div class="tabs" data-tabs="os">
+        <div class="tab-list" role="tablist" aria-label="Operating system">
+          <button type="button" role="tab" data-tab="macos" aria-selected="true">{{icon:apple}} macOS · Linux</button>
+          <button type="button" role="tab" data-tab="windows" aria-selected="false" tabindex="-1">{{icon:windows}} Windows</button>
         </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
+        <div class="tab-panel" data-panel="macos">
+          <div class="command-card">
+            <header><span>Run in the project folder</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>
         </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 class="tab-panel" data-panel="windows" hidden>
+          <div class="command-card">
+            <header><span>PowerShell</span><button class="clip-btn" data-clip="irm https://raw.githubusercontent.com/Vt-mmm/agentwatch/main/windows/setup.ps1 | iex">Copy</button></header>
+            <pre><code>irm https://raw.githubusercontent.com/Vt-mmm/agentwatch/main/windows/setup.ps1 | iex</code></pre>
+          </div>
+          <p>Installs WSL2, Ubuntu, Piagent and Agent Watch. Details in <a href="/en/windows">Windows</a>.</p>
         </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>
+      <p>Skip the extras with <code>--no-mcp</code>, <code>--no-subagents</code>, <code>--no-herdr</code> or <code>--global-only</code>.</p>
     </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">Let the agent read the project</h3>
-        <p>In a new repository, ask the agent to read the project (read-only) and record its project context under <span class="inline-code">.pi/</span>. No separate command: plain language is enough.</p>
-        <div class="command-card">
-          <header><span>Read the project</span><button class="clip-btn" data-clip="Inspect this project read-only and record its project context.">Copy</button></header>
-          <pre><code>Inspect this project read-only and record its project context.</code></pre>
-        </div>
+      <h3 id="open-project">Open a project</h3>
+      <p>Terminal and the dashboard share one history. Company mode opens with <code>piagent studio</code> once the key is imported through Agent Watch.</p>
+      <div class="command-card">
+        <header><span>Pick one</span><button class="clip-btn" data-clip="piagent dashboard">Copy</button></header>
+        <pre><code>piagent dashboard          # browser, personal mode
+pi                         # Terminal, personal mode
+piagent studio --web       # company mode</code></pre>
       </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>
+      <h3 id="read-project">Let the agent read the project</h3>
+      <p>In a new repository, ask the agent to read it (read-only) and record the project context in <code>.pi/</code>. No special command is needed.</p>
+      <div class="command-card">
+        <header><span>First message</span><button class="clip-btn" data-clip="Read this project (read-only) and record the project context.">Copy</button></header>
+        <pre><code>Read this project (read-only) and record the project context.</code></pre>
       </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
+      <h3 id="profile-and-permission">Pick a profile and permission</h3>
+      <p>The profile decides which files are protected and which checks run. Permission: <code>read-only</code> to explore, <code>workspace-write</code> for normal coding.</p>
+      <div class="command-card">
+        <header><span>Slash commands</span><button class="clip-btn" data-clip="/profile setup&#10;/permission workspace-write">Copy</button></header>
+        <pre><code>/profile setup
 /permission workspace-write</code></pre>
-        </div>
       </div>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="run-workflow">Run a workflow</h3>
-        <p>State the work and the intent (edit, read-only, plan first) in plain language. Start a new session with <span class="inline-code">/new</span> for context-heavy work.</p>
-        <div class="command-card">
-          <header><span>Assign work</span><button class="clip-btn" data-clip="Implement the requested change and run the project tests.&#10;Review the current diff. Read-only.">Copy</button></header>
-          <pre><code>Implement the requested change and run the project tests.
+      <h3 id="ask">Ask in plain language</h3>
+      <p>Say what you need and how: edit, read-only, or plan first. For context-heavy work, start a fresh session with <code>/new</code>.</p>
+      <div class="command-card">
+        <header><span>Examples</span><button class="clip-btn" data-clip="Fix the pagination bug in /orders, then run the project's tests.">Copy</button></header>
+        <pre><code>Fix the pagination bug in /orders, then run the project's tests.
 Review the current diff. Read-only.</code></pre>
-        </div>
       </div>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="verify-before-handoff">Check before you hand over</h3>
-        <p>Ask the agent to run the project's checks (tests, type check, build) and read the real output; in company mode the Harness asks for this itself. 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>
+      <h3 id="check">Check the installation</h3>
+      <p>After installing or changing releases, run the doctor on the project. Every finding comes with the fix.</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>
     </article>
+  </div>
+</section>
 
-    <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>
+<section class="section">
+  <h2 id="supported">Supported systems</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Environment</th><th>Status</th></tr></thead>
+      <tbody>
+        <tr><td>macOS Apple Silicon</td><td>Verified for this release.</td></tr>
+        <tr><td>Linux x64</td><td>Verified in CI.</td></tr>
+        <tr><td>macOS Intel, Linux ARM64</td><td>Supported; run the doctor and smoke tests before a wide rollout.</td></tr>
+        <tr><td>Windows (WSL2)</td><td>The way to run Piagent on Windows, in both personal and company mode.</td></tr>
+        <tr><td>Native Windows</td><td>Preview of personal mode; <code>piagent-update</code> is not available yet.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>Using Herdr?</strong>
+    <p>Install Herdr <em>before</em> <code>piagent-setup</code> to get its Pi integration; if you install it later, run <code>piagent-setup --global-only</code> again. Herdr arranges terminals; it is not a protection layer. See the <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/herdr-workflow.md">Herdr workflow</a>.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="next">Next</h2>
+  <div class="card-grid">
+    <a class="doc-card" href="/en/update"><span class="card-kicker">{{icon:refresh}} Operate</span><h3>Update &amp; uninstall</h3><p>New releases, team pins, rollback, and an uninstall that previews first.</p></a>
+    <a class="doc-card" href="/en/ecosystem"><span class="card-kicker">{{icon:network}} Get started</span><h3>Ecosystem</h3><p>When to use your own model and when to use Agent Studio.</p></a>
+    <a class="doc-card" href="/en/permissions"><span class="card-kicker">{{icon:key}} Build</span><h3>Permission modes</h3><p>The four permission levels and when to use each.</p></a>
+    <a class="doc-card" href="/en/mcp"><span class="card-kicker">{{icon:plug}} MCP</span><h3>MCP</h3><p>Pinned presets, server management and the approval gate.</p></a>
   </div>
 </section>

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

@@ -0,0 +1,80 @@
+<section class="section">
+  <h2 id="update">Update</h2>
+  <p>The dashboard and Terminal check for a new release every hour. When one is out, the dashboard opens a dialog with what will change, <strong>Update now</strong> and <strong>Later</strong> (asks again in an hour). To run it yourself, one command:</p>
+  <div class="command-card">
+    <header><span>Move to the latest release</span><button class="clip-btn" data-clip="piagent-update">Copy</button></header>
+    <pre><code>piagent-update</code></pre>
+  </div>
+  <p>Restart the dashboard afterwards so the new interface takes effect.</p>
+
+  <h3 id="what-it-does">What it does, in order</h3>
+  <ol>
+    <li>Resolves the target release and the Pi version it pins.</li>
+    <li>Installs that Pi host, then replaces the <code>piagent-update</code> helper.</li>
+    <li>Checks the version actually on disk before running the installer.</li>
+    <li>With <code>--project</code>: migrates the project's state and runs <code>piagent-doctor --strict-share</code>.</li>
+  </ol>
+  <div class="callout">
+    <strong>Not from a git checkout</strong>
+    <p><code>piagent-update</code> refuses to run when the global package is a link to a source repository, so it never overwrites code you are editing.</p>
+  </div>
+
+  <h3 id="options">Common options</h3>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Command</th><th>Use when</th></tr></thead>
+      <tbody>
+        <tr><td><code>piagent-update --check</code></td><td>You only want to know whether a release is out.</td></tr>
+        <tr><td><code>piagent-update --dry-run</code></td><td>You want to see what would be installed, changing nothing.</td></tr>
+        <tr><td><code>piagent-update --version X.Y.Z</code></td><td>You want exactly one release, newer or older.</td></tr>
+        <tr><td><code>piagent-update --project .</code></td><td>You want the current project migrated too.</td></tr>
+        <tr><td><code>--no-host</code> · <code>--no-package</code> · <code>--no-migrate</code></td><td>You want to skip a step.</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="pin-for-a-team">Pin one release for a team</h2>
+  <p>For a team rollout, install the exact Pi host and platform release, then run the installer in stable mode. The <code>--dry-run</code> step prints what would change.</p>
+  <div class="command-card">
+    <header><span>Pinned install</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@{{piHost}}&#10;npm install -g --ignore-scripts @piagent/platform@{{version}}&#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@{{piHost}}
+npm install -g --ignore-scripts @piagent/platform@{{version}}
+piagent-install --stable --dry-run
+piagent-install --stable</code></pre>
+  </div>
+  <p>Installed from a package, <code>.pi/settings.json</code> records <code>npm:@piagent/platform@&lt;version&gt;</code>: the same value on every machine, so the team can commit it. The full procedure is in the <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/release-install-policy.md">release &amp; install policy</a>.</p>
+</section>
+
+<section class="section">
+  <h2 id="rollback">Roll back</h2>
+  <p>Rolling back is deliberate, never automatic. Move to a specific release with the same update command:</p>
+  <div class="command-card">
+    <header><span>Back to a previous release</span><button class="clip-btn" data-clip="piagent-update --version X.Y.Z --dry-run&#10;piagent-update --version X.Y.Z">Copy</button></header>
+    <pre><code>piagent-update --version X.Y.Z --dry-run
+piagent-update --version X.Y.Z</code></pre>
+  </div>
+  <p>To change only the Pi package and keep the host: <code>piagent-install --version vX.Y.Z --resolve-tag</code>. Run <code>piagent-doctor</code> on the project afterwards.</p>
+</section>
+
+<section class="section">
+  <h2 id="uninstall">Uninstall</h2>
+  <p><code>piagent-uninstall</code> only reports what it would remove and exits. It acts with <code>--apply</code>, because it edits Pi settings that other tools also write to.</p>
+  <div class="command-card">
+    <header><span>Preview, then remove</span><button class="clip-btn" data-clip="piagent-uninstall&#10;piagent-uninstall --apply">Copy</button></header>
+    <pre><code>piagent-uninstall
+piagent-uninstall --apply
+npm uninstall -g @piagent/platform</code></pre>
+  </div>
+  <p>Add-ons, the Pi host and project state are opt-in: <code>--with-addons</code>, <code>--with-host</code>, <code>--project &lt;path&gt;</code>.</p>
+  <div class="callout ok-callout">
+    <strong>Never removed</strong>
+    <p>Credentials, trust, sessions, todos and <code>.pi/memory/</code> are kept under every combination of flags. Files generated from a template and then edited (<code>AGENTS.md</code>, <code>.pi/settings.json</code>) are only listed, for you to decide.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="windows">On Windows</h2>
+  <p>Run the same PowerShell command you installed with: it updates WSL, Piagent and Agent Watch. See <a href="/en/windows">Windows</a>.</p>
+</section>