ollanet 0.6.1 → 0.6.3

package/README.md

@@ -192,12 +192,13 @@ optimizeDeps: { exclude: ["ollanet"] },
 | `ollanet pull <machine> <model>` | Ask that host to download / update a library model |
 | `ollanet show <machine> <model>` | Inspect Modelfile / params / capabilities (`[tuned]` when it looks like Finetuna) |
 | `ollanet rm <machine> <model> --yes` | Delete a model from that host’s disk |
-| `ollanet ps [machine]` | Models loaded in VRAM (omit machine = every discovered host) |
+| `ollanet ps [machine]` | Models loaded in VRAM, with CPU/GPU % (omit machine = every discovered host) |
 | `ollanet prompt …` | Send a prompt / continue a chat (`--file` for `.txt` / `.md`) |
 | `ollanet compare …` | Same prompt on 2–5 models; summary + `compares/<id>.md` |
 | `ollanet chats` | List or inspect saved transcripts |
 | `ollanet bench …` | Benchmark models for tok/s + lightweight quality checks |
 | `ollanet mcp` | Stdio [MCP](https://modelcontextprotocol.io) server for agents |
+| `ollanet help [command]` | This overview, or one command’s flags (`ollanet help bench`, `ollanet bench help`) |
 
 ### `scan` options
 
@@ -339,10 +340,12 @@ ollanet bench localhost gemma4:12b --hot --runs 5
 ```
 
 Runs a built-in suite (`quick` default, or `--suite full`) against one or more **completion**
-models: instruction checks once, throughput case repeated (`--runs`, default 3) with
+models: instruction checks once, 256-token throughput repeated (`--runs`, default 3) with
 pinned `num_predict` / `seed` / `temperature`. Reports median tok/s + spread.
-`--hot` discards the first throughput run and leaves models loaded so the counted
-repeats are already warm (Finetuna steady-state). Under `--all`,
+`--hot` discards the first 256-token run and leaves models loaded so the counted
+repeats are already warm (Finetuna steady-state). `--suite full` also runs json/reason
+checks and **one** 1024-token prose generation (`tok/s long`) — closer to a long chat
+reply. Under `--all`,
 skips non-completion models (embeddings); multimodal `completion`+`vision` models stay in
 (early-stop / pass_rate handle text-suite failures). Use `--exclude-vision` to drop them.
 Saves `benchmarks/<id>.json` (or `~/.ollanet/benchmarks/` when installed).
@@ -350,7 +353,7 @@ See [`docs/bench-spec.md`](docs/bench-spec.md) for measurement rules.
 
 `quick` has only two scored checks (`ping`, `math`), so `pass` is a coarse
 liveness/sanity gauge (`0/2`, `1/2`, `2/2`) — not “50% broken.” Use `--suite full`
-when you care more about the quality signal.
+when you care more about the quality signal or want the long tok/s column.
 
 ## Discovery
 

package/dist/argv.d.ts

@@ -3,6 +3,11 @@
  */
 import type { GenerateSettings } from "./config.js";
 export type UsageFn = () => never;
+export declare function isHelpFlag(arg: string): boolean;
+/** Intentional help: stdout, exit 0. */
+export declare function printHelp(text: string): never;
+/** Usage error: stderr, exit 1. */
+export declare function failUsage(text: string): never;
 export declare function takeValue(args: string[], flag: string, usage: UsageFn): string;
 /** `--name value` or `--name=value`. Returns undefined if `arg` is not this flag. */
 export declare function takeFlag(arg: string, name: string, args: string[], usage: UsageFn): string | undefined;

package/dist/argv.js

@@ -1,3 +1,16 @@
+export function isHelpFlag(arg) {
+    return arg === "--help" || arg === "-h";
+}
+/** Intentional help: stdout, exit 0. */
+export function printHelp(text) {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    process.exit(0);
+}
+/** Usage error: stderr, exit 1. */
+export function failUsage(text) {
+    console.error(text);
+    process.exit(1);
+}
 export function takeValue(args, flag, usage) {
     const value = args.shift();
     if (!value) {

package/dist/bench-suite.d.ts

@@ -3,14 +3,21 @@ export interface BenchCase {
     id: string;
     role: CaseRole;
     prompt: string;
-    /** Cap for this case; throughput uses settings.throughput_num_predict. */
+    /** Cap for this case. Peak throughput uses `--num-predict` when omitted. */
     num_predict?: number;
+    /**
+     * Throughput attempts. Omit to use `--runs` (and `--hot` discard).
+     * Set `1` for a single large shot that does not repeat.
+     */
+    repeats?: number;
     format?: "json";
     check?: (content: string) => {
         ok: boolean;
         detail?: string;
     };
 }
+/** Pinned length for `full`'s prose throughput case (`throughput_long`). */
+export declare const LONG_THROUGHPUT_NUM_PREDICT = 1024;
 export type SuiteName = "quick" | "full";
 export declare function getSuiteCases(suite: SuiteName): BenchCase[];
 export declare function suiteRevision(suite: SuiteName): string;

package/dist/bench-suite.js

@@ -2,6 +2,8 @@
  * Built-in ollanet bench suites, checkers, and revision hashes.
  */
 import { createHash } from "node:crypto";
+/** Pinned length for `full`'s prose throughput case (`throughput_long`). */
+export const LONG_THROUGHPUT_NUM_PREDICT = 1024;
 const MATH_ANSWER = 323;
 const REASON_ANSWER = 42;
 function lastTokenNormalized(content) {
@@ -104,18 +106,23 @@ const FULL_EXTRA = [
     {
         id: "reason",
         role: "check",
-        prompt: "A box has 10 apples. You eat 3, then buy 5 more, then give away 2 times as many as you ate. " +
-            "How many apples are left? Reply with only the final number.",
+        prompt: "Start with 40. Add 7. Subtract 5. Reply with only the final number.",
         num_predict: 48,
-        // 10 - 3 + 5 - 6 = 6... wait: gave away 2*3=6, so 10-3+5-6=6. Spec said 42 as placeholder.
-        // Use a problem that clearly ends at 42:
-        // Actually rewrite for 42: "Start with 40. Add 7. Subtract 5. Reply with only the number." => 42
         check: checkExpectedInt(REASON_ANSWER),
     },
+    {
+        id: "throughput_long",
+        role: "throughput",
+        // Chat-shaped tokens (markdown, lists, a table) at a long pin. Anti-EOS
+        // so done_reason=length; one shot (not --runs) so full stays usable.
+        prompt: "Write a detailed trade-off briefing for a product team choosing a web UI stack. " +
+            "Compare at least two options. Use markdown headings, bullet lists, and at least one table. " +
+            "Keep adding sections (testing, hiring, migration, failure modes, cost) without wrapping up. " +
+            "Do not write a closing recommendation that ends the piece. Do not stop early.",
+        num_predict: LONG_THROUGHPUT_NUM_PREDICT,
+        repeats: 1,
+    },
 ];
-// Fix reason prompt to match REASON_ANSWER
-FULL_EXTRA[FULL_EXTRA.length - 1].prompt =
-    "Start with 40. Add 7. Subtract 5. Reply with only the final number.";
 export function getSuiteCases(suite) {
     if (suite === "full")
         return [...QUICK_CASES, ...FULL_EXTRA];

package/dist/bench.d.ts

@@ -1 +1,2 @@
+export declare function helpText(): string;
 export declare function main(): Promise<void>;

package/dist/bench.js

@@ -2,46 +2,55 @@
  * ollanet bench — speed + lightweight quality suite against Ollama models.
  */
 import { defaultModelForHost, loadConfig, machineSettingsForHost, mergeSettings, settingsFromEnv, } from "./config.js";
-import { comparabilityKey, getSuiteCases, median, suiteRevision, } from "./bench-suite.js";
+import { comparabilityKey, getSuiteCases, LONG_THROUGHPUT_NUM_PREDICT, median, suiteRevision, } from "./bench-suite.js";
 import { benchmarksDir, newBenchId, saveBenchmark } from "./bench-store.js";
 import { readFile } from "node:fs/promises";
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
-import { consumeSettingsFlag, parseNumberFlag, takeFlag } from "./argv.js";
+import { consumeSettingsFlag, failUsage, isHelpFlag, parseNumberFlag, printHelp, takeFlag } from "./argv.js";
 import { resolveTarget } from "./target.js";
 import { projectPath } from "./paths.js";
 import { contextLengthForModel, isCompletionCapable, isVisionCapable, ollamaChat, ollamaShow, ollamaTags, ollamaUnload, ollamaVersion, ollamaPs, psHasModel, shouldWarnNoThinking, vramForModel, waitUntilUnloaded, } from "./ollama-chat.js";
 const MODEL_COL = 34;
 const BENCH_TIMEOUT_MS = envInt("OLLAMA_BENCH_TIMEOUT_MS", 60_000);
 const UNLOAD_WAIT_MS = envInt("OLLAMA_BENCH_UNLOAD_WAIT_MS", 60_000);
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet bench <machine|ip> [model...] [options]
   ollanet bench <machine|ip> --all [options]
 
 Examples:
   ollanet bench studio gemma3:12b --runs 5
   ollanet bench studio gemma3:12b --hot --runs 5
+  ollanet help bench
+
+Fixed suite (not compare). Checks run once; 256-token throughput repeats --runs times.
+Median tok/s excludes early-stops. Unload is between models, not between repeats.
+full adds json/reason checks plus one 1024-token prose generation (tok/s long).
 
 Options:
   --all                 Every completion-capable model from /api/tags
   --exclude-vision      With --all, skip models that advertise vision
   --suite quick|full    Prompt suite (default quick)
-  --runs <n>            Throughput repeats (default 3)
-  --hot                 Discard first throughput run; keep models loaded
-  --warmup / --no-warmup
+  --runs <n>            Counted 256-token throughput repeats (default 3)
+  --hot                 Discard first 256-token throughput run; keep models loaded
+  --warmup              Short discarded call before timed cases (default on)
+  --no-warmup           Skip the short warmup (--hot implies this)
   --cold-load           Measure cold load via unload + /api/ps
-  --num-predict <n>     Pin throughput length (default 256)
-  --num-ctx <n>
-  --keep-alive <value>
-  --think / --no-think
-  --judge --judge-model <name>
+  --num-predict <n>     Pin 256-token throughput length (default 256; not the long case)
+  --num-ctx <n>         Context window override
+  --keep-alive <value>  Keep model loaded (e.g. 5m, 0, -1)
+  --think / --no-think  Thinking tokens (default off)
+  --judge               Second pass: score check answers 1–5
+  --judge-model <name>  Required with --judge (no default)
   --json                Machine-readable stdout
-  --save / --no-save
-  --fail-fast
+  --save / --no-save    Persist under benchmarks/ (default on)
+  --fail-fast           Stop remaining models after the first hard error
   --fail-on-error       Exit 2 if any model/case errored
 
-See docs/bench-spec.md for measurement rules.`);
-    process.exit(1);
+See docs/bench-spec.md for measurement rules.`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function isLoopback(host) {
     return (host.source === "localhost" ||
@@ -57,6 +66,26 @@ function resolveModelName(tags, query) {
     const prefix = tags.find((t) => t.name.toLowerCase().startsWith(`${q}:`) || q.startsWith(`${t.name.toLowerCase()}:`));
     return prefix?.name;
 }
+function pinnedNumPredict(caseDef, throughputNumPredict) {
+    if (caseDef.role === "throughput") {
+        return caseDef.num_predict ?? throughputNumPredict;
+    }
+    return caseDef.num_predict ?? 32;
+}
+/** At least the global timeout; longer pins need room to finish at ~8 tok/s. */
+function attemptTimeoutMs(numPredict) {
+    return Math.max(BENCH_TIMEOUT_MS, Math.ceil(numPredict / 8) * 1000);
+}
+function caseReps(caseDef, runs, hot) {
+    if (caseDef.role !== "throughput")
+        return 1;
+    if (caseDef.repeats != null)
+        return caseDef.repeats;
+    return runs + (hot ? 1 : 0);
+}
+function discardFirstThroughput(caseDef, hot) {
+    return hot && caseDef.role === "throughput" && caseDef.repeats == null;
+}
 function tokPerSec(chunk) {
     if (chunk.eval_count == null || chunk.eval_duration == null || chunk.eval_duration <= 0) {
         return undefined;
@@ -90,7 +119,9 @@ function parseArgs(argv) {
     const positional = [];
     while (args.length > 0) {
         const arg = args.shift();
-        if (arg === "--" || arg === "--help" || arg === "-h")
+        if (isHelpFlag(arg))
+            printHelp(helpText());
+        if (arg === "--")
             usage();
         if (arg === "--all") {
             all = true;
@@ -275,9 +306,7 @@ async function runColdLoad(baseUrl, model, keepAlive) {
     }
 }
 async function runCaseAttempt(opts) {
-    const numPredict = opts.caseDef.role === "throughput"
-        ? opts.throughputNumPredict
-        : (opts.caseDef.num_predict ?? 32);
+    const numPredict = pinnedNumPredict(opts.caseDef, opts.throughputNumPredict);
     const settings = mergeSettings(opts.settings, {
         temperature: 0,
         seed: 0,
@@ -293,7 +322,7 @@ async function runCaseAttempt(opts) {
             messages: [{ role: "user", content: opts.caseDef.prompt }],
             stream: false,
             writeStdout: false,
-            timeoutMs: BENCH_TIMEOUT_MS,
+            timeoutMs: attemptTimeoutMs(numPredict),
             settings,
         });
         const wallMs = Date.now() - wall0;
@@ -363,12 +392,23 @@ async function runCaseAttempt(opts) {
 function countedAttempts(attempts) {
     return attempts.filter((a) => !a.discarded);
 }
-function summarizeModel(cases, cold, selfJudge) {
-    const throughput = cases.find((c) => c.id === "throughput");
-    const counted = countedAttempts(throughput?.attempts ?? []);
+function speedFrom(cases, id) {
+    const counted = countedAttempts(cases.find((c) => c.id === id)?.attempts ?? []);
     const fullLen = counted.filter((a) => !a.error && !a.early_stop && a.tok_s != null);
     const toks = fullLen.map((a) => a.tok_s);
-    const earlyStopCount = counted.filter((a) => a.early_stop || (a.done_reason && a.done_reason !== "length")).length;
+    return {
+        median: median(toks) ?? null,
+        min: toks.length ? Math.min(...toks) : null,
+        max: toks.length ? Math.max(...toks) : null,
+    };
+}
+function summarizeModel(cases, cold, selfJudge) {
+    const peak = speedFrom(cases, "throughput");
+    const long = speedFrom(cases, "throughput_long");
+    const throughputAttempts = cases
+        .filter((c) => c.role === "throughput")
+        .flatMap((c) => countedAttempts(c.attempts));
+    const earlyStopCount = throughputAttempts.filter((a) => a.early_stop || (a.done_reason && a.done_reason !== "length")).length;
     const checkAttempts = cases
         .filter((c) => c.role === "check")
         .flatMap((c) => c.attempts)
@@ -376,9 +416,12 @@ function summarizeModel(cases, cold, selfJudge) {
     const passed = checkAttempts.filter((a) => a.quality?.pass).length;
     const passRate = checkAttempts.length > 0 ? passed / checkAttempts.length : null;
     return {
-        tok_s_median: median(toks) ?? null,
-        tok_s_min: toks.length ? Math.min(...toks) : null,
-        tok_s_max: toks.length ? Math.max(...toks) : null,
+        tok_s_median: peak.median,
+        tok_s_min: peak.min,
+        tok_s_max: peak.max,
+        tok_s_long_median: long.median,
+        tok_s_long_min: long.min,
+        tok_s_long_max: long.max,
         early_stop_count: earlyStopCount,
         pass_rate: passRate,
         load_ms: cold && cold.error == null && cold.load_ms > 0 ? cold.load_ms : cold?.error ? null : cold?.load_ms ?? null,
@@ -394,17 +437,22 @@ function printTable(machine, suite, runs, revision, compKey, models, skipped, co
         lines.push("Cold-load: on");
     if (hot)
         lines.push("Hot: first throughput run discarded; models stay loaded");
+    if (suite === "full")
+        lines.push("full: tok/s long is one 1024-token prose generation");
     lines.push("");
+    const showLong = suite === "full";
     const header = coldLoad
         ? pad("Model", MODEL_COL) +
             pad("tok/s (med)", 12) +
             pad("spread", 12) +
+            (showLong ? pad("tok/s long", 12) : "") +
             pad("load", 8) +
             pad("pass", 8) +
             "notes"
         : pad("Model", MODEL_COL) +
             pad("tok/s (med)", 12) +
             pad("spread", 12) +
+            (showLong ? pad("tok/s long", 12) : "") +
             pad("pass", 8) +
             "notes";
     lines.push(header);
@@ -438,6 +486,7 @@ function printTable(machine, suite, runs, revision, compKey, models, skipped, co
         const spread = m.summary.tok_s_min != null && m.summary.tok_s_max != null
             ? `${m.summary.tok_s_min.toFixed(1)}–${m.summary.tok_s_max.toFixed(1)}`
             : "—";
+        const tokLong = m.summary.tok_s_long_median != null ? m.summary.tok_s_long_median.toFixed(1) : "—";
         const pass = m.summary.pass_rate != null
             ? `${Math.round(m.summary.pass_rate * checkDenom(m))}/${checkDenom(m)}`
             : "—";
@@ -457,12 +506,14 @@ function printTable(machine, suite, runs, revision, compKey, models, skipped, co
             ? pad(m.name, MODEL_COL) +
                 pad(tok, 12) +
                 pad(spread, 12) +
+                (showLong ? pad(tokLong, 12) : "") +
                 pad(load, 8) +
                 pad(pass, 8) +
                 notes.join("; ")
             : pad(m.name, MODEL_COL) +
                 pad(tok, 12) +
                 pad(spread, 12) +
+                (showLong ? pad(tokLong, 12) : "") +
                 pad(pass, 8) +
                 notes.join("; ");
         lines.push(row);
@@ -575,10 +626,13 @@ export async function main() {
         hot: parsed.hot,
     });
     const suiteCases = getSuiteCases(parsed.suite);
-    const throughputReps = parsed.runs + (parsed.hot ? 1 : 0);
     const caseCount = selected.length *
-        (suiteCases.filter((c) => c.role !== "throughput").length +
-            suiteCases.filter((c) => c.role === "throughput").length * throughputReps);
+        suiteCases.reduce((n, c) => n + caseReps(c, parsed.runs, parsed.hot), 0);
+    const worstCaseMs = selected.length *
+        suiteCases.reduce((n, c) => {
+            const pin = pinnedNumPredict(c, parsed.throughputNumPredict);
+            return n + caseReps(c, parsed.runs, parsed.hot) * attemptTimeoutMs(pin);
+        }, 0);
     if (!parsed.json) {
         const skipBits = [
             skipped.filter((s) => s.reason === "non-completion").length
@@ -593,7 +647,10 @@ export async function main() {
             ` × suite=${parsed.suite} × runs=${parsed.runs}` +
             (parsed.hot ? " (hot: +1 discarded)" : ""));
         console.error(`Cases: ~${caseCount} chat calls   timeout: ${BENCH_TIMEOUT_MS}ms/case` +
-            `   worst-case ceiling: ~${Math.ceil((caseCount * BENCH_TIMEOUT_MS) / 60000)}m if every call times out`);
+            (parsed.suite === "full"
+                ? ` (long case ≥${attemptTimeoutMs(LONG_THROUGHPUT_NUM_PREDICT)}ms)`
+                : "") +
+            `   worst-case ceiling: ~${Math.ceil(worstCaseMs / 60000)}m if every call times out`);
         if (!parsed.hot && !isLoopback(host) && (selected.length >= 2 || parsed.coldLoad)) {
             const bits = [
                 selected.length >= 2 ? "unloads each model before the next" : "",
@@ -655,8 +712,8 @@ export async function main() {
         let modelError;
         for (const caseDef of suiteCases) {
             const attempts = [];
-            const discardFirst = parsed.hot && caseDef.role === "throughput";
-            const reps = caseDef.role === "throughput" ? parsed.runs + (discardFirst ? 1 : 0) : 1;
+            const discardFirst = discardFirstThroughput(caseDef, parsed.hot);
+            const reps = caseReps(caseDef, parsed.runs, parsed.hot);
             for (let i = 0; i < reps; i += 1) {
                 const discarded = discardFirst && i === 0;
                 const attempt = await runCaseAttempt({
@@ -748,6 +805,7 @@ export async function main() {
             temperature: 0,
             seed: 0,
             throughput_num_predict: parsed.throughputNumPredict,
+            throughput_long_num_predict: parsed.suite === "full" ? LONG_THROUGHPUT_NUM_PREDICT : null,
             num_ctx: baseSettings.num_ctx ?? null,
             warmup: parsed.warmup,
             hot: parsed.hot,

package/dist/chats.d.ts

@@ -6,4 +6,5 @@
  *   ollanet chats --json
  *   ollanet chats --id a1b2c3d4e5f6
  */
+export declare function helpText(): string;
 export declare function main(): Promise<void>;

package/dist/chats.js

@@ -7,16 +7,18 @@
  *   ollanet chats --id a1b2c3d4e5f6
  */
 import { loadChat, listChats, responsesDir, } from "./chat-store.js";
-import { takeFlag } from "./argv.js";
-function usage() {
-    console.error(`Usage: ollanet chats [--json] [--id <hash>]
+import { failUsage, isHelpFlag, printHelp, takeFlag } from "./argv.js";
+export function helpText() {
+    return `Usage: ollanet chats [--json] [--id <hash>]
 
 Lists transcripts in ${responsesDir()}.
 
 Options:
   --json       Machine-readable output
-  --id <hash>  Show one chat (messages included with --json, preview otherwise)`);
-    process.exit(1);
+  --id <hash>  Show one chat (messages included with --json, preview otherwise)`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function parseArgs(argv) {
     const args = [...argv];
@@ -26,8 +28,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--json") {
             json = true;
             continue;

package/dist/cli.js

@@ -28,6 +28,7 @@ Usage:
   ollanet chats [--json] [--id <hash>]
   ollanet bench <machine|ip> [model...] [--all] [options]
   ollanet mcp
+  ollanet help [command]
 
 Examples:
   ollanet scan
@@ -46,6 +47,7 @@ Examples:
   ollanet bench localhost --all
   ollanet bench localhost llama3.2:1b --runs 3
   ollanet bench localhost gemma3:12b --hot --runs 5
+  ollanet help bench           # flags for one command (also: ollanet bench help)
   ollanet mcp                  # stdio MCP server for agents
 
 Config: ~/.ollanet/config.json when installed, ./config.json in a checkout
@@ -58,10 +60,36 @@ async function main() {
     // pnpm/npm often forward a bare `--`; ignore it.
     const argv = process.argv.slice(2).filter((arg) => arg !== "--");
     const cmd = argv[0];
-    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+    if (!cmd || cmd === "-h" || cmd === "--help") {
         process.stdout.write(HELP);
         return;
     }
+    if (cmd === "help") {
+        const topic = argv[1];
+        if (!topic || topic === "-h" || topic === "--help") {
+            process.stdout.write(HELP);
+            return;
+        }
+        const { commandHelp, commandNames } = await import("./help.js");
+        const text = await commandHelp(topic);
+        if (!text) {
+            console.error(`Unknown command: ${topic}`);
+            console.error(`Try: ollanet help   (commands: ${commandNames().join(", ")})`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+        return;
+    }
+    const rest = argv.slice(1);
+    const { isHelpRequest, commandHelp } = await import("./help.js");
+    if (isHelpRequest(rest)) {
+        const text = await commandHelp(cmd);
+        if (text) {
+            process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+            return;
+        }
+    }
     if (cmd === "-v" || cmd === "--version" || cmd === "version") {
         const { readFile } = await import("node:fs/promises");
         const { projectPath } = await import("./paths.js");

package/dist/compare.d.ts

@@ -7,6 +7,7 @@
 import { type AppConfig, type GenerateSettings } from "./config.js";
 /** Used when --prompt, --file, and stdin are all omitted. */
 export declare const DEFAULT_COMPARE_PROMPT: string;
+export declare function helpText(): string;
 export interface CompareModelResult {
     model: string;
     content?: string;

package/dist/compare.js

@@ -6,7 +6,7 @@
  */
 import { configFromPartial, loadConfig, machineSettingsForHost, mergeSettings, settingsFromEnv, } from "./config.js";
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
-import { consumeSettingsFlag, takeFlag, takeValue } from "./argv.js";
+import { consumeSettingsFlag, failUsage, isHelpFlag, printHelp, takeFlag, takeValue } from "./argv.js";
 import { resolveTarget } from "./target.js";
 import { ollamaChat, ollamaTags, ollamaUnload, waitUntilUnloaded, } from "./ollama-chat.js";
 import { assemblePrompt, readPromptFile } from "./prompt-input.js";
@@ -23,8 +23,8 @@ function compareTimeoutMs() {
 function unloadWaitMs() {
     return envInt("OLLAMA_COMPARE_UNLOAD_WAIT_MS", 60_000);
 }
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet compare <machine> <model> <model> [model...]
   ollanet compare <machine> <model> <model> [model...] --prompt <text>
   ollanet compare <machine> <model> <model> [model...] --file <path.txt|.md>
@@ -49,8 +49,10 @@ Options:
   --think / --no-think
   --unload               Unload each model before the next (fairer tok/s)
   --no-save              Do not write compares/*
-  --json                 Emit the full record on stdout`);
-    process.exit(1);
+  --json                 Emit the full record on stdout`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function parseArgs(argv) {
     const args = [...argv];
@@ -65,8 +67,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--json") {
             json = true;
             continue;

package/dist/help.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Per-command help: `ollanet help bench` and `ollanet bench help`.
+ */
+export declare function canonicalCommand(name: string): string | undefined;
+export declare function commandNames(): string[];
+export declare function commandHelp(name: string): Promise<string | undefined>;
+export declare function isHelpRequest(args: string[]): boolean;

package/dist/help.js

@@ -0,0 +1,51 @@
+/**
+ * Per-command help: `ollanet help bench` and `ollanet bench help`.
+ */
+const LOADERS = {
+    scan: () => import("./scan.js"),
+    prompt: () => import("./prompt.js"),
+    chats: () => import("./chats.js"),
+    pull: () => import("./pull.js"),
+    show: () => import("./show.js"),
+    rm: () => import("./rm.js"),
+    ps: () => import("./ps.js"),
+    compare: () => import("./compare.js"),
+    bench: () => import("./bench.js"),
+    mcp: () => import("./mcp.js"),
+};
+const ALIASES = {
+    "ls-servers": "scan",
+    ask: "prompt",
+    chat: "prompt",
+    ls: "chats",
+    history: "chats",
+    download: "pull",
+    inspect: "show",
+    delete: "rm",
+    loaded: "ps",
+    vs: "compare",
+    h2h: "compare",
+    benchmark: "bench",
+};
+export function canonicalCommand(name) {
+    const key = name.trim().toLowerCase();
+    if (LOADERS[key])
+        return key;
+    return ALIASES[key];
+}
+export function commandNames() {
+    return Object.keys(LOADERS);
+}
+export async function commandHelp(name) {
+    const canon = canonicalCommand(name);
+    if (!canon)
+        return undefined;
+    const load = LOADERS[canon];
+    if (!load)
+        return undefined;
+    const mod = await load();
+    return mod.helpText();
+}
+export function isHelpRequest(args) {
+    return args.length === 1 && (args[0] === "help" || args[0] === "--help" || args[0] === "-h");
+}

package/dist/mcp.d.ts

@@ -8,4 +8,5 @@
  *
  * stdout is reserved for JSON-RPC; log only to stderr.
  */
+export declare function helpText(): string;
 export declare function main(): Promise<void>;

package/dist/mcp.js

@@ -21,6 +21,7 @@ import { removeModel } from "./rm.js";
 import { lastScan } from "./scan-store.js";
 import { scanNetwork } from "./scan.js";
 import { showModel } from "./show.js";
+import { isHelpFlag, printHelp } from "./argv.js";
 // Pin to the oldest widely-supported MCP revision. Clients may request a newer
 // date; we still answer with this — legal negotiation, max compatibility.
 const PROTOCOL_VERSION = "2024-11-05";
@@ -199,7 +200,7 @@ const TOOLS = [
     {
         name: "ollanet_ps",
         description: "List models currently loaded in VRAM. Optional machine; omit to probe every discovered host. " +
-            "scan is on-disk inventory; ps is what is resident right now.",
+            "scan is on-disk inventory; ps is what is resident right now, with CPU/GPU %.",
         inputSchema: {
             type: "object",
             properties: {
@@ -487,7 +488,29 @@ async function handleRequest(msg, version) {
             fail(id, -32601, `Method not found: ${method}`);
     }
 }
+export function helpText() {
+    return `Usage:
+  ollanet mcp
+
+Stdio MCP server (no extra npm deps). stdout is JSON-RPC; logs go to stderr.
+
+Tools:
+  ollanet_scan          Discover hosts + models (lan, all, last)
+  ollanet_prompt        Prompt a host or continue with chat_id
+  ollanet_compare       Same prompt on 2–5 models
+  ollanet_pull          Pull / update a model on a host
+  ollanet_show          Inspect a model
+  ollanet_rm            Delete a model (confirm: true)
+  ollanet_ps            Models loaded in VRAM
+  ollanet_list_chats    Saved transcripts
+  ollanet_get_chat      One chat by id
+
+Example Cursor config: { "command": "npx", "args": ["-y", "ollanet", "mcp"] }`;
+}
 export async function main() {
+    if (process.argv.slice(2).some((arg) => isHelpFlag(arg))) {
+        printHelp(helpText());
+    }
     const version = await packageVersion();
     console.error(`ollanet mcp ${version} (stdio) — tools: ${TOOLS.map((t) => t.name).join(", ")}`);
     const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });

package/dist/ollama-chat.d.ts

@@ -74,6 +74,8 @@ export declare function ollamaVersion(baseUrl: string, timeoutMs: number): Promi
 export interface PsModel {
     name?: string;
     model?: string;
+    /** Total resident bytes (VRAM + CPU/RAM). */
+    size?: number;
     size_vram?: number;
     context_length?: number;
     digest?: string;

package/dist/prompt.d.ts

@@ -12,6 +12,7 @@
  *   ollanet chats
  */
 import { type AppConfig, type GenerateSettings } from "./config.js";
+export declare function helpText(): string;
 export interface PromptRunOptions {
     machine?: string;
     model?: string;

package/dist/prompt.js

@@ -17,14 +17,14 @@ import { configPath, defaultModelForHost, loadConfig, machineSettingsForHost, me
 import { envInt, findDiscoveredHost, ollamaBaseUrl, resolveHost, shortName, } from "./hosts.js";
 import { ollamaChat } from "./ollama-chat.js";
 import { assemblePrompt, readPromptFile } from "./prompt-input.js";
-import { consumeSettingsFlag, takeFlag, takeValue } from "./argv.js";
+import { consumeSettingsFlag, failUsage, isHelpFlag, printHelp, takeFlag, takeValue } from "./argv.js";
 import { listTargets, resolveTarget } from "./target.js";
 /** Prompt/chat HTTP timeout (ms). 0 = no timeout. Separate from scan's OLLAMA_TIMEOUT_MS. */
 function promptTimeoutMs() {
     return envInt("OLLAMA_PROMPT_TIMEOUT_MS", 600_000);
 }
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet prompt <machine> [model] <prompt...>
   ollanet prompt --chat <hash> <prompt...>
   ollanet prompt <machine> --chat <hash> <prompt...>
@@ -57,8 +57,10 @@ Options:
   --no-think             Disable thinking (default) so tokens go to the reply
   --file <path>          Prompt from a .txt or .md file (joins argv / stdin)
   --no-stream            Wait for the full response
-  --json                 Emit final response JSON (implies --no-stream)`);
-    process.exit(1);
+  --json                 Emit final response JSON (implies --no-stream)`;
+}
+function usage() {
+    failUsage(helpText());
 }
 /**
  * Heuristic for an optional positional model token.
@@ -136,8 +138,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--no-stream") {
             stream = false;
             continue;

package/dist/ps.d.ts

@@ -5,9 +5,15 @@
  *   ollanet ps studio
  */
 import { type AppConfig } from "./config.js";
+export declare function helpText(): string;
 export interface LoadedModel {
     name: string;
+    size?: number;
     size_vram?: number;
+    cpu_percent?: number;
+    gpu_percent?: number;
+    /** Same wording as `ollama ps` PROCESSOR (e.g. "100% GPU", "83%/17% CPU/GPU"). */
+    processor?: string;
     context_length?: number;
     digest?: string;
     tuned: boolean;
@@ -27,5 +33,11 @@ export interface PsOptions {
 export interface PsResult {
     hosts: LoadedHost[];
 }
+/** Match `ollama ps` PROCESSOR: CPU% from (size - size_vram) / size. */
+export declare function processorSplit(size?: number, sizeVram?: number): {
+    cpu_percent?: number;
+    gpu_percent?: number;
+    processor?: string;
+};
 export declare function listLoaded(opts?: PsOptions): Promise<PsResult>;
 export declare function main(): Promise<void>;

package/dist/ps.js

@@ -7,14 +7,14 @@
 import { configFromPartial, loadConfig } from "./config.js";
 import { discoverHosts, envInt, ollamaBaseUrl, shortName, } from "./hosts.js";
 import { ollamaPs, ollamaPsRequired } from "./ollama-chat.js";
-import { takeFlag } from "./argv.js";
+import { failUsage, isHelpFlag, printHelp, takeFlag } from "./argv.js";
 import { resolveTarget } from "./target.js";
 import { looksTuned } from "./tuned.js";
 function psTimeoutMs() {
     return envInt("OLLAMA_PS_TIMEOUT_MS", 10_000);
 }
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet ps [machine]
   ollanet ps --machine <name>
 
@@ -23,12 +23,15 @@ Examples:
   ollanet ps studio
   ollanet ps studio --json
 
-scan lists models on disk. ps lists what is loaded in VRAM right now.
+scan lists models on disk. ps lists what is loaded and the CPU/GPU split
+(same rule as ollama ps: size_vram / size).
 
 Options:
   --machine <name>   One host (default: every discovered host)
-  --json             Emit result JSON on stdout`);
-    process.exit(1);
+  --json             Emit result JSON on stdout`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function parseArgs(argv) {
     const args = [...argv];
@@ -39,8 +42,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--json") {
             json = true;
             continue;
@@ -74,11 +77,31 @@ function formatBytes(bytes) {
     }
     return `${value.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
 }
+/** Match `ollama ps` PROCESSOR: CPU% from (size - size_vram) / size. */
+export function processorSplit(size, sizeVram) {
+    const total = size ?? 0;
+    const vram = sizeVram ?? 0;
+    if (vram === 0 && total === 0)
+        return {};
+    if (vram === 0)
+        return { cpu_percent: 100, gpu_percent: 0, processor: "100% CPU" };
+    if (total > 0 && vram === total) {
+        return { cpu_percent: 0, gpu_percent: 100, processor: "100% GPU" };
+    }
+    if (vram > total || total === 0)
+        return { processor: "Unknown" };
+    const cpu = Math.round(((total - vram) / total) * 100);
+    const gpu = 100 - cpu;
+    return { cpu_percent: cpu, gpu_percent: gpu, processor: `${cpu}%/${gpu}% CPU/GPU` };
+}
 function toLoaded(m) {
     const name = (m.name ?? m.model ?? "").trim();
+    const split = processorSplit(m.size, m.size_vram);
     return {
         name,
+        size: m.size,
         size_vram: m.size_vram,
+        ...split,
         context_length: m.context_length,
         digest: m.digest,
         tuned: looksTuned(name),
@@ -141,7 +164,7 @@ function printPs(result) {
                 const vram = formatBytes(m.size_vram);
                 const ctx = m.context_length != null ? `ctx ${m.context_length}` : "";
                 const tag = m.tuned ? " [tuned]" : "";
-                const meta = [vram ? `VRAM ${vram}` : "", ctx].filter(Boolean).join("  ");
+                const meta = [vram ? `VRAM ${vram}` : "", m.processor, ctx].filter(Boolean).join("  ");
                 process.stdout.write(meta ? `  ${m.name}  ${meta}${tag}\n` : `  ${m.name}${tag}\n`);
             }
         }

package/dist/pull.d.ts

@@ -8,6 +8,7 @@
  */
 import type { AppConfig } from "./config.js";
 import { type PullChunk } from "./ollama-chat.js";
+export declare function helpText(): string;
 export interface PullOptions {
     machine: string;
     model: string;

package/dist/pull.js

@@ -8,14 +8,14 @@
  */
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
 import { ollamaPull } from "./ollama-chat.js";
-import { takeFlag } from "./argv.js";
+import { failUsage, isHelpFlag, printHelp, takeFlag } from "./argv.js";
 import { resolveTarget } from "./target.js";
 /** Pull HTTP timeout (ms). 0 = none. Large models can take hours. */
 function pullTimeoutMs() {
     return envInt("OLLAMA_PULL_TIMEOUT_MS", 0);
 }
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet pull <machine> <model>
   ollanet pull --machine <name> --model <name>
 
@@ -33,8 +33,10 @@ Options:
   --model <name>     Model to pull (e.g. gemma3:12b)
   --insecure         Allow HTTP / self-signed model registries
   --no-stream        Wait for a single final response (no progress chunks)
-  --json             Emit result JSON on stdout`);
-    process.exit(1);
+  --json             Emit result JSON on stdout`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function parseArgs(argv) {
     const args = [...argv];
@@ -48,8 +50,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--insecure") {
             insecure = true;
             continue;

package/dist/rm.d.ts

@@ -4,6 +4,7 @@
  *   ollanet rm studio llama3.2:1b --yes
  */
 import type { AppConfig } from "./config.js";
+export declare function helpText(): string;
 export interface RemoveOptions {
     machine: string;
     model: string;

package/dist/rm.js

@@ -6,13 +6,13 @@
 import { createInterface } from "node:readline";
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
 import { ollamaDelete } from "./ollama-chat.js";
-import { takeFlag } from "./argv.js";
+import { failUsage, isHelpFlag, printHelp, takeFlag } from "./argv.js";
 import { resolveTarget } from "./target.js";
 function rmTimeoutMs() {
     return envInt("OLLAMA_RM_TIMEOUT_MS", 30_000);
 }
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet rm <machine> <model> --yes
   ollanet rm --machine <name> --model <name> --yes
 
@@ -27,8 +27,10 @@ Options:
   --machine <name>   Host (discovered name, MagicDNS, hostname, or IP[:port])
   --model <name>     Model to delete
   --yes              Required unless stdin is a TTY and you confirm
-  --json             Emit result JSON on stdout`);
-    process.exit(1);
+  --json             Emit result JSON on stdout`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function parseArgs(argv) {
     const args = [...argv];
@@ -41,8 +43,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--yes" || arg === "-y") {
             yes = true;
             continue;

package/dist/scan.d.ts

@@ -54,4 +54,5 @@ export interface ScanPayload {
 }
 /** Programmatic scan used by CLI `--json`, MCP, and `import { scanNetwork } from "ollanet"`. */
 export declare function scanNetwork(options?: ScanOptions): Promise<ScanPayload>;
+export declare function helpText(): string;
 export declare function main(): Promise<void>;

package/dist/scan.js

@@ -7,6 +7,7 @@ import { configFromPartial, loadConfig } from "./config.js";
 import { discoverHosts, envInt, ollamaPort, shortName, } from "./hosts.js";
 import { lastScanPath, loadLastScan, saveLastScan } from "./scan-store.js";
 import { looksTuned } from "./tuned.js";
+import { isHelpFlag, printHelp } from "./argv.js";
 function scanTimeoutMs() {
     return envInt("OLLAMA_TIMEOUT_MS", 2500);
 }
@@ -184,7 +185,30 @@ export async function scanNetwork(options = {}) {
     }
     return payload;
 }
+export function helpText() {
+    return `Usage:
+  ollanet scan [--json] [--all] [--lan] [--last]
+
+Examples:
+  ollanet scan
+  ollanet scan --lan
+  ollanet scan --last
+  ollanet scan --json
+
+Discovers Ollama hosts (localhost, config, OLLANET_HOSTS, Tailscale) and lists
+models. --lan is an opt-in TCP sweep of local /24s on port 11434.
+
+Options:
+  --json     Machine-readable output
+  --all      Also probe offline Tailscale peers
+  --lan      TCP-scan local LAN CIDRs for open Ollama ports
+  --last     Reprint the last saved scan (no network)
+  --cached   Same as --last`;
+}
 export async function main() {
+    if (process.argv.slice(2).some((arg) => isHelpFlag(arg))) {
+        printHelp(helpText());
+    }
     const includeOffline = process.argv.includes("--all");
     const jsonOut = process.argv.includes("--json");
     const lanScan = process.argv.includes("--lan");

package/dist/show.d.ts

@@ -5,6 +5,7 @@
  */
 import { type OllamaShowInfo } from "./ollama-chat.js";
 import type { AppConfig } from "./config.js";
+export declare function helpText(): string;
 export interface ShowOptions {
     machine: string;
     model: string;

package/dist/show.js

@@ -5,14 +5,14 @@
  */
 import { envInt, ollamaBaseUrl, shortName } from "./hosts.js";
 import { ollamaShow } from "./ollama-chat.js";
-import { takeFlag } from "./argv.js";
+import { failUsage, isHelpFlag, printHelp, takeFlag } from "./argv.js";
 import { resolveTarget } from "./target.js";
 import { looksTuned } from "./tuned.js";
 function showTimeoutMs() {
     return envInt("OLLAMA_SHOW_TIMEOUT_MS", 30_000);
 }
-function usage() {
-    console.error(`Usage:
+export function helpText() {
+    return `Usage:
   ollanet show <machine> <model>
   ollanet show --machine <name> --model <name>
 
@@ -26,8 +26,10 @@ Tuned Finetuna-style names are marked [tuned].
 Options:
   --machine <name>   Host (discovered name, MagicDNS, hostname, or IP[:port])
   --model <name>     Model to inspect
-  --json             Emit result JSON on stdout`);
-    process.exit(1);
+  --json             Emit result JSON on stdout`;
+}
+function usage() {
+    failUsage(helpText());
 }
 function parseArgs(argv) {
     const args = [...argv];
@@ -39,8 +41,8 @@ function parseArgs(argv) {
         const arg = args.shift();
         if (arg === "--")
             continue;
-        if (arg === "--help" || arg === "-h")
-            usage();
+        if (isHelpFlag(arg))
+            printHelp(helpText());
         if (arg === "--json") {
             json = true;
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ollanet",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Discover and talk to Ollama on any reachable network — CLI, MCP, and a Node library",
   "type": "module",
   "bin": {