1 files changed, 51 insertions, 2 deletions
diff --git a/docs/usage.html b/docs/usage.html
index 6d770d0..7d71b1c 100644
--- a/docs/usage.html
+++ b/docs/usage.html
@@ -66,7 +66,7 @@ no key, no token.</p>
   <tr><td>Latest tag</td><td><code>v4.6.146</code> — <a href="/newos4/refs/">see refs</a></td></tr>
   <tr><td>Writes</td><td>none. <code>git-receive-pack</code> answers 403; there is no SSH endpoint</td></tr>
   <tr><td>Private data</td><td>stripped from every commit before publication — see <a href="/usage.html#scope">Scope</a></td></tr>
-  <tr><td>Reading it</td><td><a href="/about/">rendered README</a> · <a href="/newos4/tree/">file tree</a> · <a href="/newos4/log/">history</a></td></tr>
+  <tr><td>Reading it</td><td><a href="/newos4/about/">rendered README</a> · <a href="/newos4/tree/">file tree</a> · <a href="/newos4/log/">history</a></td></tr>
 </table>
 
 <h2 id="linux">Linux</h2>
@@ -172,6 +172,55 @@ also clone a public HTTPS repository without an account.</p>
 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>Install</h3>
+<pre><code>node -v                       # needs Node &gt;= 22.19.0
+npm install -g @earendil-works/pi-coding-agent
+pi --version                  # e.g. 1.5.0</code></pre>
+<p style="color:var(--dim);font-size:.9rem">That package installs the <code>pi</code> binary
+(<code>bin: pi → dist/bundle/cli.js</code>). A system-wide install lands in
+<code>/usr/lib/node_modules/@earendil-works/pi-coding-agent</code>; a user install needs
+<code>~/.local/bin</code> on <code>PATH</code>.</p>
+
+<h3>Point it at Ollama</h3>
+<p>Ollama speaks the OpenAI wire format on <code>http://127.0.0.1:11434/v1</code> by default, which is exactly
+what <code>pi</code> expects. Two files under <code>~/.pi/agent/</code> do the whole job:</p>
+<pre><code>// ~/.pi/agent/models.json
+{
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434/v1",
+      "api": "openai-completions",
+      "apiKey": "ollama",
+      "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false },
+      "models": [
+        { "id": "llama3.2:latest", "name": "Llama 3.2 (local)" },
+        { "id": "qwen2.5-coder:7b", "name": "Qwen2.5 Coder 7B (local)" }
+      ]
+    }
+  }
+}</code></pre>
+<pre><code>// ~/.pi/agent/settings.json
+{ "defaultProvider": "ollama", "defaultModel": "llama3.2:latest" }</code></pre>
+<p style="color:var(--dim);font-size:.9rem"><code>baseUrl</code> points at your daemon — use
+<code>http://localhost:11434/v1</code> for a local Ollama, or your own host:port. <code>apiKey</code> must be a
+non-empty string because the client sends it as a bearer token; Ollama ignores the value. The two
+<code>compat</code> flags off are what this provider needs.</p>
+
+<div class="warn">
+  <strong>Pulling a model in Ollama is not enough.</strong> It must also be listed under
+  <code>models[]</code>. Undeclared, <code>pi --model llama3.2:latest</code> fails with
+  <code>Error: Model "llama3.2:latest" not found. Use --list-models</code> — that is the single most common
+  configuration mistake and it looks like a connection problem.
+</div>
+
+<h3>Verify the wiring</h3>
+<pre><code>pi --list-models | grep ollama           # your declared ids, with context limits
+ollama list                              # what the daemon actually serves
+pi -p --no-session --no-tools --model llama3.2:latest "Reply with exactly: LOCAL OK"</code></pre>
+<p style="color:var(--dim);font-size:.9rem">A reply of <code>LOCAL OK</code> means the whole chain works:
+config → local daemon → model. Ids ending in <code>-cloud</code> are relayed by Ollama to
+<code>ollama.com</code> and need an <code>ollama signin</code>; local tags have no suffix.</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
 
@@ -275,7 +324,7 @@ repository that cannot accept them.</p>
 <footer>
   Served from the same repository it documents ·
   Source: <a href="/newos4/tree/docs/usage.html">docs/usage.html</a> ·
-  <a href="/about/">README</a> · MIT licence · updated 2026-11-05
+  <a href="/newos4/about/">README</a> · MIT licence · updated 2026-11-05
 </footer>
 
 </div>