docs(newos4): automating with the pi agent (recipes verified against pi 0.80.3)

Four recipes on the usage page: one-shot @file analysis, --mode json + jq for
scripts, a read-only --tools allowlist for tree inspection, and a cron-able
digest. Every flag shown was exercised on this host first; the retired-default
model gotcha (HTTP 410 'was retired') is documented because it wasted a run.
Adds the untrusted-input warning: pi auto-loads AGENTS.md/skills from the working
directory, so a public clone must run with --no-approve and no write tools.

1 files changed, 69 insertions, 0 deletions

diff --git a/docs/usage.html b/docs/usage.html
index 031bc4e..6d770d0 100644
--- a/docs/usage.html
+++ b/docs/usage.html
@@ -167,6 +167,75 @@ termux-wake-unlock</code></pre>
 <code>git clone</code> command. <a href="https://workingcopy.app/">Working Copy</a> is a GUI alternative that can
 also clone a public HTTPS repository without an account.</p>
 
+<h2 id="pi">Automating with the pi agent</h2>
+<p><code>pi</code> is a terminal coding agent (a Node CLI — <code>pi --help</code>). Everything below uses
+only documented flags, treats the mirror as read-only, and was run against <code>pi 0.80.3</code> before being
+written down.</p>
+
+<h3>1. One-shot: analyse a file, print an answer, exit</h3>
+<pre><code>git clone --depth 1 https://newos.webx11.duckdns.org/newos4.git /tmp/newos4
+
+pi -p --no-session --no-tools --model gemma4:31b-cloud \
+   @/tmp/newos4/README.md "In one sentence, what is this repository?"</code></pre>
+<p style="color:var(--dim);font-size:.9rem">Output: <em>“This repository contains newOS4, a browser-based
+terminal featuring a filesystem, command shell, editor, and AI agent backed by WebDAV storage and WebX11 user
+spaces.”</em> — <code>-p</code> is the non-interactive mode, <code>@file</code> inlines the file,
+<code>--no-tools</code> forbids tool use entirely, <code>--no-session</code> leaves nothing behind.</p>
+
+<h3>2. Machine-readable output for scripts</h3>
+<pre><code>pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \
+   @/tmp/newos4/CHANGELOG.md "Summarise the newest release in one line" \
+ | jq -r 'select(.type=="message_end" and .message.role=="assistant")
+          | .message.content[0].text'</code></pre>
+<p style="color:var(--dim);font-size:.9rem"><code>--mode json</code> emits one JSON object per line. The event
+types in order are <code>session</code>, <code>agent_start</code>, <code>turn_start</code>,
+<code>message_start</code>/<code>message_end</code> (the assistant's text is in
+<code>message.content[].text</code>), <code>turn_end</code>, <code>agent_end</code>. Parse on
+<code>message_end</code> and you never have to scrape the terminal UI.</p>
+
+<h3>3. Let it read the tree — with a read-only tool allowlist</h3>
+<pre><code>cd /tmp/newos4
+pi -p --no-session --tools read,bash --no-approve --model gemma4:31b-cloud \
+   "Which files does main.html load, and where is the module loader defined?"</code></pre>
+<p style="color:var(--dim);font-size:.9rem">Tool names are <code>read</code>, <code>bash</code>,
+<code>edit</code>, <code>write</code>; <code>--tools</code> is an allowlist, so leaving <code>edit</code> and
+<code>write</code> out makes the run read-only by construction. <code>--tools read</code> alone cannot list a
+directory — <code>read</code> reads files — so add <code>bash</code> when it needs to <code>ls</code>.</p>
+
+<h3>Flags worth knowing for automation</h3>
+<table>
+  <tr><th>Flag</th><th>What it buys you</th></tr>
+  <tr><td><code>--list-models</code></td><td>What your install can actually reach, with context and output limits</td></tr>
+  <tr><td><code>--model</code></td><td>Pin the model in scripts. A saved default can be retired server-side and fail with HTTP 410 “was retired” — passing <code>--model</code> keeps a job reproducible</td></tr>
+  <tr><td><code>--offline</code></td><td>Skip startup network calls (<code>PI_OFFLINE=1</code> also works)</td></tr>
+  <tr><td><code>--session-id</code> / <code>--continue</code></td><td>Resume the same conversation across runs instead of re-sending context</td></tr>
+  <tr><td><code>--append-system-prompt &lt;file&gt;</code></td><td>Append text or a file's contents to the system prompt — the cheap way to give every run your house rules</td></tr>
+  <tr><td><code>--skill &lt;path&gt;</code></td><td>Load a skill file or directory; <code>--no-skills</code> / <code>--no-context-files</code> turn discovery off</td></tr>
+</table>
+
+<h3>Safety: this repository is untrusted input</h3>
+<div class="warn">
+  <code>pi</code> auto-loads project files (<code>AGENTS.md</code>, <code>CLAUDE.md</code>, skills, extensions)
+  from the working directory. For a clone of a public repository you did not write, run with
+  <code>--no-approve</code> (ignores project-local files) and a tool allowlist that cannot write —
+  <code>--tools read</code>, or <code>--tools read,bash</code> if it must list files. Never point a
+  full-tool run at a repo you have not read: a prompt-injection in a README is executed the same way your own
+  instructions would be.
+</div>
+
+<h3>A cron-able digest</h3>
+<pre><code>#!/bin/sh
+# nightly: refresh the mirror, ask one question, write markdown
+set -eu
+cd /tmp/newos4 2>/dev/null || git clone -q --depth 1 https://newos.webx11.duckdns.org/newos4.git /tmp/newos4
+git pull -q --ff-only
+pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \
+   @CHANGELOG.md "Three bullets: what changed in the newest release?" \
+ | jq -r 'select(.type=="message_end" and .message.role=="assistant") | .message.content[0].text' \
+ &gt; "$HOME/newos4-digest.md"</code></pre>
+<p style="color:var(--dim);font-size:.9rem">The mirror only fast-forwards, so <code>git pull --ff-only</code>
+can never wedge. Nothing here can push — the repository refuses <code>receive-pack</code> at three levels.</p>
+
 <h2 id="updating">Updating later</h2>
 <pre><code>cd newos4
 git pull --ff-only          # the mirror only ever fast-forwards