yonyon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yonatan Gross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# yonyon
+
+Command line client for the public [yonyon.ai](https://yonyon.ai) agent API.
+
+Ask the site's agent a question, list the portfolio projects, wire up the MCP server, or grab the
+booking link, without writing an HTTP integration first.
+
+The API is public and unauthenticated. There is no key to set, no config file to write, and no login
+step. The only constraint is rate: **10 requests per IP per minute**, shared across every endpoint.
+
+## Install
+
+Run it without installing anything:
+
+```bash
+npx yonyon ask "What has Yonatan built with MCP?"
+```
+
+Or install it globally:
+
+```bash
+npm install -g yonyon
+yonyon --help
+```
+
+Requires Node.js 24 or newer.
+
+## Commands
+
+### `yonyon ask "<question>"`
+
+Ask the agent about Yonatan Gross, his projects, or his services. The default path is `POST /ask`,
+the single-shot endpoint built for server-side callers.
+
+```console
+$ yonyon ask "What is OrchestKit?"
+OrchestKit is an open-source Claude Code agent framework with 100+ skills,
+35+ agents, and 200+ hooks.
+
+Follow-ups you could ask:
+  What else has he built?
+  Is he available for consulting?
+```
+
+Add `--stream` to use `POST /api/chat` instead and print tokens as they arrive. Add `--json` to get
+the raw `/ask` response body.
+
+```bash
+yonyon ask "Is he available for consulting?" --stream
+yonyon ask "List his projects" --json
+```
+
+### `yonyon projects [--limit N] [--json]`
+
+List the portfolio projects from `GET /api/v1/projects`.
+
+```console
+$ yonyon projects --limit 2
+NAME                  DESCRIPTION                                    URL
+--------------------  ---------------------------------------------  ------------------------------------------------
+OrchestKit            Open-source Claude Code agent framework.       https://yonyon.ai/projects/orchestkit
+AI Operations Platfo  Production WhatsApp AI (RAG), commerce, cont…  https://yonyon.ai/projects/ai-operations-platform
+```
+
+`--limit` accepts 1 to 50, the range the API itself enforces. Use `--json` for the raw body, which
+also carries `total` and `nextCursor` for pagination.
+
+```bash
+yonyon projects --json
+```
+
+### `yonyon mcp [--tools] [--json]`
+
+Print ready-to-paste MCP client configuration for the yonyon.ai MCP server, a JSON-RPC 2.0
+Streamable HTTP endpoint that needs no auth.
+
+```console
+$ yonyon mcp
+MCP endpoint: https://yonyon.ai/api/mcp
+Transport: Streamable HTTP. Authentication: none.
+
+Add it to Claude Code:
+  claude mcp add --transport http yonyon https://yonyon.ai/api/mcp
+
+Or add this to .mcp.json:
+{
+  "mcpServers": {
+    "yonyon": {
+      "type": "http",
+      "url": "https://yonyon.ai/api/mcp"
+    }
+  }
+}
+```
+
+`--tools` queries `tools/list` live and prints each tool with its description. `--json` prints only
+the config object, so it can be redirected into a file.
+
+```bash
+yonyon mcp --tools
+yonyon mcp --json > .mcp.json
+```
+
+### `yonyon book [--no-open]`
+
+Print the link for a free 15-minute intro call, and open it in the default browser.
+
+```console
+$ yonyon book
+Book a free 15-minute intro call: https://cal.com/yonyon
+Opening it in your browser.
+```
+
+The browser is only opened when stdout is a terminal, so piping the command never launches anything.
+Pass `--no-open` to suppress it explicitly.
+
+```bash
+yonyon book --no-open
+```
+
+### `yonyon docs [--json]`
+
+Print the discovery map: every machine-readable document an agent can read to learn what the site
+offers and how to call it.
+
+```console
+$ yonyon docs
+Discovery documents
+URL                                                 WHAT IT IS
+--------------------------------------------------  ------------------------------------------------
+https://yonyon.ai/llms.txt                          Short site summary written for LLMs
+https://yonyon.ai/llms-full.txt                     Full bio, projects, services and FAQ
+https://yonyon.ai/developers                        Human-readable API and MCP documentation
+...
+```
+
+```bash
+yonyon docs --json
+```
+
+## Global options
+
+| Option             | Meaning                                                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `-h`, `--help`     | Show help. Works per command too: `yonyon ask --help`.                                                     |
+| `-v`, `--version`  | Print the CLI version.                                                                                     |
+| `--base-url <url>` | Target another deployment. Defaults to `https://yonyon.ai`, or the `YONYON_BASE_URL` environment variable. |
+| `--timeout <ms>`   | Per-request timeout. Defaults to 60000 for `ask` and 15000 elsewhere.                                      |
+| `--json`           | Machine-readable output, on the commands that support it.                                                  |
+
+Point it at a local dev server:
+
+```bash
+yonyon projects --base-url https://portfolio.localhost
+```
+
+## Exit codes
+
+| Code | Meaning                                                                   |
+| ---- | ------------------------------------------------------------------------- |
+| `0`  | Success.                                                                  |
+| `1`  | The request failed: network error, timeout, non-2xx response, rate limit. |
+| `2`  | A usage mistake: unknown command, unknown flag, missing or invalid value. |
+
+Rate limiting gets its own message rather than a bare HTTP 429:
+
+```console
+$ yonyon ask "hello"
+yonyon: Rate limited by yonyon.ai (10 requests per IP per minute). Retry in 43s.
+  The public API is unauthenticated, so the budget is shared per source IP.
+  Wait for the window to reset and run the command again.
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm test          # vitest, network fully mocked
+pnpm exec tsc --noEmit
+pnpm run build     # emits dist/
+node dist/index.js --help
+```
+
+The CLI has zero runtime dependencies. Argument parsing is hand-rolled, which is smaller than any
+parser library at this command count.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/args.js

@@ -0,0 +1,110 @@
+import { usageError } from "./errors.js";
+/** Flags that take a value. Everything else is a boolean switch. */
+const VALUE_FLAGS = new Set(["base-url", "limit", "timeout"]);
+const ALIASES = {
+    h: "help",
+    v: "version",
+};
+/**
+ * Hand-rolled parser. The CLI has five commands and eight flags, which is well
+ * under the size where a dependency pays for itself.
+ *
+ * Supports `--flag`, `--flag=value`, `--flag value`, `--no-flag`, `-h`, `-v`,
+ * and `--` to stop flag parsing. Bare `-` and unknown short clusters are
+ * treated as positionals so a question can start with a dash.
+ */
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = new Map();
+    let sawTerminator = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (sawTerminator) {
+            positionals.push(token);
+            continue;
+        }
+        if (token === "--") {
+            sawTerminator = true;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            if (body === "")
+                throw usageError("Empty flag name.");
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                const name = body.slice(0, eq);
+                const value = body.slice(eq + 1);
+                if (!VALUE_FLAGS.has(name)) {
+                    throw usageError(`Flag --${name} does not take a value.`);
+                }
+                flags.set(name, value);
+                continue;
+            }
+            if (body.startsWith("no-")) {
+                flags.set(body.slice(3), false);
+                continue;
+            }
+            if (VALUE_FLAGS.has(body)) {
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith("--")) {
+                    throw usageError(`Flag --${body} needs a value.`);
+                }
+                flags.set(body, next);
+                i++;
+                continue;
+            }
+            flags.set(body, true);
+            continue;
+        }
+        // Short flags: only the documented single-letter aliases, so that a
+        // negative number or a dash-led question stays a positional.
+        if (token.length === 2 && token.startsWith("-") && ALIASES[token[1]]) {
+            flags.set(ALIASES[token[1]], true);
+            continue;
+        }
+        positionals.push(token);
+    }
+    const command = positionals.shift() ?? "";
+    return { command, positionals, flags };
+}
+/** Reject any flag the command does not understand, instead of ignoring it. */
+export function assertKnownFlags(flags, allowed, command) {
+    const known = new Set([...allowed, "help", "version", "base-url", "timeout"]);
+    for (const name of flags.keys()) {
+        if (!known.has(name)) {
+            throw usageError(`Unknown flag --${name} for "yonyon ${command}".`, [
+                `Run "yonyon ${command} --help" to see the supported flags.`,
+            ]);
+        }
+    }
+}
+export function boolFlag(flags, name) {
+    return flags.get(name) === true;
+}
+/** True unless the flag was explicitly negated with `--no-<name>`. */
+export function enabledUnlessNegated(flags, name) {
+    return flags.get(name) !== false;
+}
+export function stringFlag(flags, name) {
+    const value = flags.get(name);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw usageError(`Flag --${name} needs a value.`);
+    }
+    return value;
+}
+export function intFlag(flags, name, range) {
+    const raw = stringFlag(flags, name);
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw)) {
+        throw usageError(`--${name} must be a whole number, got "${raw}".`);
+    }
+    const value = Number(raw);
+    if (value < range.min || value > range.max) {
+        throw usageError(`--${name} must be between ${range.min} and ${range.max}, got ${value}.`);
+    }
+    return value;
+}

package/dist/cli.js

@@ -0,0 +1,112 @@
+import { createRequire } from "node:module";
+import { assertKnownFlags, boolFlag, intFlag, parseArgs, stringFlag } from "./args.js";
+import { askCommand, ASK_HELP } from "./commands/ask.js";
+import { bookCommand, BOOK_HELP } from "./commands/book.js";
+import { docsCommand, DOCS_HELP } from "./commands/docs.js";
+import { mcpCommand, MCP_HELP } from "./commands/mcp.js";
+import { projectsCommand, PROJECTS_HELP } from "./commands/projects.js";
+import { CliError, usageError } from "./errors.js";
+import { FAST_TIMEOUT_MS, resolveBaseUrl, SLOW_TIMEOUT_MS } from "./http.js";
+import { line, processIo } from "./io.js";
+const require = createRequire(import.meta.url);
+export function version() {
+    const pkg = require("../package.json");
+    return pkg.version ?? "0.0.0";
+}
+const HELP = `yonyon - command line client for the public yonyon.ai agent API.
+
+Usage: yonyon <command> [options]
+
+Commands:
+  ask "<question>"   Ask the agent about Yonatan, his projects or his services
+  projects           List the portfolio projects
+  mcp                Print MCP client config, or list the server's tools
+  book               Print (and open) the intro-call booking link
+  docs               Print the machine-readable discovery map
+
+Global options:
+  -h, --help         Show help. Works per command too: yonyon ask --help
+  -v, --version      Print the CLI version
+  --base-url <url>   Target another deployment (default: https://yonyon.ai,
+                     or the YONYON_BASE_URL environment variable)
+  --timeout <ms>     Per-request timeout in milliseconds
+  --json             Machine-readable output, where the command supports it
+
+The API is public and unauthenticated. There is nothing to configure and no
+key to set. It is rate limited to 10 requests per IP per minute.
+
+Examples:
+  yonyon ask "What has Yonatan built with MCP?"
+  yonyon projects --limit 3
+  yonyon mcp --tools
+  yonyon docs --json`;
+const COMMAND_HELP = {
+    ask: ASK_HELP,
+    projects: PROJECTS_HELP,
+    mcp: MCP_HELP,
+    book: BOOK_HELP,
+    docs: DOCS_HELP,
+};
+/** Commands whose backend is an LLM get the roomier timeout. */
+const SLOW_COMMANDS = new Set(["ask"]);
+export async function run(argv, io = processIo) {
+    try {
+        const { command, positionals, flags } = parseArgs(argv);
+        if (boolFlag(flags, "version") && !command) {
+            line(io, version());
+            return 0;
+        }
+        if (!command) {
+            line(io, HELP);
+            return boolFlag(flags, "help") ? 0 : 1;
+        }
+        const help = COMMAND_HELP[command];
+        if (help === undefined) {
+            throw usageError(`Unknown command "${command}".`, [
+                `Known commands: ${Object.keys(COMMAND_HELP).join(", ")}.`,
+                'Run "yonyon --help" for usage.',
+            ]);
+        }
+        if (boolFlag(flags, "help")) {
+            line(io, help);
+            return 0;
+        }
+        const baseUrl = resolveBaseUrl(stringFlag(flags, "base-url"));
+        const timeoutMs = intFlag(flags, "timeout", { min: 1, max: 600_000 }) ??
+            (SLOW_COMMANDS.has(command) ? SLOW_TIMEOUT_MS : FAST_TIMEOUT_MS);
+        const ctx = { baseUrl, timeoutMs };
+        switch (command) {
+            case "ask":
+                await askCommand(positionals, flags, ctx, io);
+                break;
+            case "projects":
+                await projectsCommand(flags, ctx, io);
+                break;
+            case "mcp":
+                await mcpCommand(flags, ctx, io);
+                break;
+            case "book":
+                assertKnownFlags(flags, ["open", "json"], "book");
+                bookCommand(flags, io);
+                break;
+            case "docs":
+                docsCommand(flags, baseUrl, io);
+                break;
+            /* c8 ignore next 2 */
+            default:
+                throw usageError(`Unknown command "${command}".`);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            io.err(`yonyon: ${error.message}\n`);
+            for (const hint of error.hints)
+                io.err(`  ${hint}\n`);
+            return error.exitCode;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        io.err(`yonyon: unexpected error: ${message}\n`);
+        return 1;
+    }
+}

package/dist/commands/ask.js

@@ -0,0 +1,69 @@
+import { assertKnownFlags, boolFlag } from "../args.js";
+import { usageError } from "../errors.js";
+import { createTrailerStripper, splitFollowUps } from "../format.js";
+import { postJson, postStream } from "../http.js";
+import { line } from "../io.js";
+export const ASK_HELP = `Usage: yonyon ask "<question>" [options]
+
+Ask the yonyon.ai agent a question about Yonatan Gross, his projects, or his
+services. Answers come from POST /ask, the single-shot endpoint built for
+server-side callers.
+
+Options:
+  --stream           Use the multi-turn POST /api/chat endpoint and print
+                     tokens as they arrive, instead of one-shot /ask.
+  --json             Print the raw JSON response. Ignored with --stream,
+                     which has no JSON representation.
+  --base-url <url>   Point at another deployment (default: https://yonyon.ai).
+  --timeout <ms>     Per-request timeout (default: 60000).
+
+Examples:
+  yonyon ask "What has Yonatan built with MCP?"
+  yonyon ask "Is he available for consulting?" --stream
+  yonyon ask "List his projects" --json`;
+export async function askCommand(positionals, flags, ctx, io) {
+    assertKnownFlags(flags, ["stream", "json"], "ask");
+    const question = positionals.join(" ").trim();
+    if (!question) {
+        throw usageError('yonyon ask needs a question, for example: yonyon ask "What is OrchestKit?"');
+    }
+    if (boolFlag(flags, "stream")) {
+        // The streamed reply carries the same FOLLOW_UPS trailer as /ask, so strip
+        // it on the way through rather than printing a marker meant for the web UI.
+        const stripper = createTrailerStripper();
+        let printed = "";
+        await postStream(ctx, "/api/chat", { messages: [{ role: "user", content: question }] }, (chunk) => {
+            const text = stripper.push(chunk);
+            if (text) {
+                printed += text;
+                io.out(text);
+            }
+        });
+        const tail = stripper.flush();
+        if (tail) {
+            printed += tail;
+            io.out(tail);
+        }
+        if (!printed.endsWith("\n"))
+            io.out("\n");
+        return;
+    }
+    const response = await postJson(ctx, "/ask", { query: question });
+    if (boolFlag(flags, "json")) {
+        line(io, JSON.stringify(response, null, 2));
+        return;
+    }
+    const answer = typeof response.answer === "string" ? response.answer : "";
+    if (!answer) {
+        line(io, "The API returned no answer for that question.");
+        return;
+    }
+    const { text, followUps } = splitFollowUps(answer);
+    line(io, text);
+    if (followUps.length > 0) {
+        line(io);
+        line(io, "Follow-ups you could ask:");
+        for (const followUp of followUps)
+            line(io, `  ${followUp}`);
+    }
+}

package/dist/commands/book.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+import { assertKnownFlags, boolFlag, enabledUnlessNegated } from "../args.js";
+import { line } from "../io.js";
+export const BOOKING_URL = "https://cal.com/yonyon";
+export const BOOK_HELP = `Usage: yonyon book [options]
+
+Print the booking link for a free 15-minute intro call, and open it in the
+default browser when stdout is a terminal.
+
+Options:
+  --no-open          Print the URL without opening a browser. Opening is also
+                     skipped automatically when stdout is not a TTY.
+  --json             Print the booking URL as JSON.
+
+Examples:
+  yonyon book
+  yonyon book --no-open`;
+/** Platform-appropriate opener. Detached and unref'd so we never block exit. */
+export function openInBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    const args = process.platform === "win32" ? ["", url] : [url];
+    try {
+        const child = spawn(command, args, {
+            stdio: "ignore",
+            detached: true,
+            shell: process.platform === "win32",
+        });
+        // A missing opener must not crash the command; the URL is already printed.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Same reasoning: printing the URL is the contract, opening is a bonus.
+    }
+}
+export function bookCommand(flags, io, open = openInBrowser) {
+    assertKnownFlags(flags, ["open", "json"], "book");
+    if (boolFlag(flags, "json")) {
+        line(io, JSON.stringify({ bookingUrl: BOOKING_URL, durationMinutes: 15, price: "free" }, null, 2));
+        return;
+    }
+    line(io, `Book a free 15-minute intro call: ${BOOKING_URL}`);
+    const wanted = enabledUnlessNegated(flags, "open");
+    if (!wanted)
+        return;
+    if (!io.isTty) {
+        line(io, "(Not a terminal, so the browser was not opened. Use the link above.)");
+        return;
+    }
+    open(BOOKING_URL);
+    line(io, "Opening it in your browser.");
+}

package/dist/commands/docs.js

@@ -0,0 +1,58 @@
+import { assertKnownFlags, boolFlag } from "../args.js";
+import { table } from "../format.js";
+import { line } from "../io.js";
+export const DOCS_HELP = `Usage: yonyon docs [options]
+
+Print the discovery map: every machine-readable document an agent can read to
+learn what yonyon.ai offers and how to call it.
+
+Options:
+  --json             Print the map as JSON.
+  --base-url <url>   Point at another deployment (default: https://yonyon.ai).
+
+Examples:
+  yonyon docs
+  yonyon docs --json`;
+/** Every path here was verified live against https://yonyon.ai on 2026-08-21. */
+const ENTRIES = [
+    { path: "/llms.txt", what: "Short site summary written for LLMs" },
+    { path: "/llms-full.txt", what: "Full bio, projects, services and FAQ" },
+    { path: "/developers", what: "Human-readable API and MCP documentation" },
+    { path: "/developers.md", what: "The same developer docs as markdown" },
+    { path: "/.well-known/openapi.json", what: "OpenAPI 3.1 spec for the public HTTP API" },
+    { path: "/.well-known/agent-skills/index.json", what: "Agent skills index" },
+    { path: "/.well-known/mcp.json", what: "MCP server descriptor" },
+    { path: "/auth.md", what: "Authentication notes (there is none, by design)" },
+];
+const ENDPOINTS = [
+    { path: "/ask", what: 'POST {"query":"..."} for a single-shot JSON answer' },
+    { path: "/api/chat", what: 'POST {"messages":[...]} for a streaming reply' },
+    { path: "/api/v1/projects", what: "GET the portfolio projects, cursor paginated" },
+    { path: "/api/mcp", what: "JSON-RPC 2.0 Streamable HTTP MCP server" },
+];
+export function docsCommand(flags, baseUrl, io) {
+    assertKnownFlags(flags, ["json"], "docs");
+    const absolute = (entries) => entries.map((entry) => ({ url: `${baseUrl}${entry.path}`, what: entry.what }));
+    if (boolFlag(flags, "json")) {
+        line(io, JSON.stringify({
+            baseUrl,
+            documents: absolute(ENTRIES),
+            endpoints: absolute(ENDPOINTS),
+            booking: "https://cal.com/yonyon",
+            rateLimit: "10 requests per IP per minute, unauthenticated",
+        }, null, 2));
+        return;
+    }
+    line(io, "Discovery documents");
+    line(io, table(["URL", "WHAT IT IS"], absolute(ENTRIES).map((e) => [e.url, e.what]), {
+        shrinkable: [1],
+    }));
+    line(io);
+    line(io, "Callable endpoints");
+    line(io, table(["URL", "HOW TO CALL IT"], absolute(ENDPOINTS).map((e) => [e.url, e.what]), {
+        shrinkable: [1],
+    }));
+    line(io);
+    line(io, "Booking: https://cal.com/yonyon");
+    line(io, "Rate limit: 10 requests per IP per minute. No API key, no OAuth.");
+}

package/dist/commands/mcp.js

@@ -0,0 +1,60 @@
+import { assertKnownFlags, boolFlag } from "../args.js";
+import { postJson } from "../http.js";
+import { line } from "../io.js";
+export const MCP_HELP = `Usage: yonyon mcp [options]
+
+Print ready-to-paste client configuration for the yonyon.ai MCP server, a
+JSON-RPC 2.0 Streamable HTTP endpoint that needs no auth.
+
+Options:
+  --tools            Also query tools/list live and print each tool name
+                     with its description.
+  --json             Print only the .mcp.json block, for piping into a file.
+  --base-url <url>   Point at another deployment (default: https://yonyon.ai).
+  --timeout <ms>     Per-request timeout (default: 15000).
+
+Examples:
+  yonyon mcp
+  yonyon mcp --tools
+  yonyon mcp --json > .mcp.json`;
+function configBlock(endpoint) {
+    return JSON.stringify({ mcpServers: { yonyon: { type: "http", url: endpoint } } }, null, 2);
+}
+export async function mcpCommand(flags, ctx, io) {
+    assertKnownFlags(flags, ["tools", "json"], "mcp");
+    const endpoint = `${ctx.baseUrl}/api/mcp`;
+    if (boolFlag(flags, "json")) {
+        line(io, configBlock(endpoint));
+        return;
+    }
+    line(io, `MCP endpoint: ${endpoint}`);
+    line(io, "Transport: Streamable HTTP. Authentication: none.");
+    line(io);
+    line(io, "Add it to Claude Code:");
+    line(io, `  claude mcp add --transport http yonyon ${endpoint}`);
+    line(io);
+    line(io, "Or add this to .mcp.json:");
+    line(io, configBlock(endpoint));
+    if (!boolFlag(flags, "tools")) {
+        line(io);
+        line(io, "Run 'yonyon mcp --tools' to list the tools the server exposes.");
+        return;
+    }
+    const response = await postJson(ctx, "/api/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }, { accept: "application/json, text/event-stream" });
+    line(io);
+    if (response.error) {
+        line(io, `Tools unavailable: ${response.error.message ?? "the server returned a JSON-RPC error."}`);
+        return;
+    }
+    const tools = response.result?.tools ?? [];
+    if (tools.length === 0) {
+        line(io, "The server reported no tools.");
+        return;
+    }
+    line(io, `Tools (${tools.length}):`);
+    for (const tool of tools) {
+        line(io, `  ${tool.name ?? "(unnamed)"}`);
+        if (tool.description)
+            line(io, `      ${tool.description}`);
+    }
+}

package/dist/commands/projects.js

@@ -0,0 +1,46 @@
+import { assertKnownFlags, boolFlag, intFlag } from "../args.js";
+import { table, truncate } from "../format.js";
+import { getJson } from "../http.js";
+import { line } from "../io.js";
+/** The API rejects anything outside this range with HTTP 400 invalid_limit. */
+const LIMIT_RANGE = { min: 1, max: 50 };
+export const PROJECTS_HELP = `Usage: yonyon projects [options]
+
+List the portfolio projects published at GET /api/v1/projects.
+
+Options:
+  --limit <n>        Return at most n projects (1-50). Default: all.
+  --json             Print the raw JSON response, including nextCursor.
+  --base-url <url>   Point at another deployment (default: https://yonyon.ai).
+  --timeout <ms>     Per-request timeout (default: 15000).
+
+Examples:
+  yonyon projects
+  yonyon projects --limit 2
+  yonyon projects --json`;
+export async function projectsCommand(flags, ctx, io) {
+    assertKnownFlags(flags, ["limit", "json"], "projects");
+    const limit = intFlag(flags, "limit", LIMIT_RANGE);
+    const query = limit === undefined ? "" : `?limit=${limit}`;
+    const response = await getJson(ctx, `/api/v1/projects${query}`);
+    if (boolFlag(flags, "json")) {
+        line(io, JSON.stringify(response, null, 2));
+        return;
+    }
+    const projects = response.projects ?? [];
+    if (projects.length === 0) {
+        line(io, "No projects returned.");
+        return;
+    }
+    const rows = projects.map((project) => [
+        project.name ?? "",
+        truncate(project.desc ?? "", 60),
+        project.url ?? "",
+    ]);
+    line(io, table(["NAME", "DESCRIPTION", "URL"], rows, { shrinkable: [1] }));
+    const total = response.total;
+    if (typeof total === "number" && projects.length < total) {
+        line(io);
+        line(io, `Showing ${projects.length} of ${total}. Use --limit or --json for the cursor.`);
+    }
+}

package/dist/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Every failure the CLI reports on purpose. `exitCode` 2 means "you typed
+ * something wrong", 1 means "the request or the network failed".
+ */
+export class CliError extends Error {
+    exitCode;
+    /** Extra lines printed under the message, for hints the user can act on. */
+    hints;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = options.exitCode ?? 1;
+        this.hints = options.hints ?? [];
+    }
+}
+/** A usage mistake: bad flag, missing argument, unknown command. */
+export function usageError(message, hints = []) {
+    return new CliError(message, { exitCode: 2, hints });
+}

package/dist/format.js

@@ -0,0 +1,134 @@
+/** Column widths are derived from the data, then clamped to the terminal. */
+const MIN_COLUMN = 8;
+export function terminalWidth(fallback = 100) {
+    const columns = process.stdout.columns;
+    return typeof columns === "number" && columns > 20 ? columns : fallback;
+}
+export function truncate(value, max) {
+    if (max <= 1)
+        return value.slice(0, Math.max(0, max));
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+/**
+ * Render rows as a plain aligned table. No box drawing: the output is meant to
+ * survive a pipe into grep or awk.
+ *
+ * `shrinkable` names the columns that may be truncated when the line does not
+ * fit the terminal. Columns left out are printed whole, which is what a URL
+ * column needs: a truncated link is worse than a wrapped one.
+ */
+export function table(headers, rows, options = {}) {
+    if (rows.length === 0)
+        return "";
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => (row[index] ?? "").length)));
+    const shrinkable = options.shrinkable ?? headers.map((_, index) => index);
+    // Shrink the widest shrinkable column until the whole line fits the terminal.
+    const gutter = 2;
+    const budget = terminalWidth() - gutter * (headers.length - 1);
+    let total = widths.reduce((sum, width) => sum + width, 0);
+    while (total > budget) {
+        let widest = -1;
+        for (const index of shrinkable) {
+            if (widths[index] <= MIN_COLUMN)
+                continue;
+            if (widest === -1 || widths[index] > widths[widest])
+                widest = index;
+        }
+        if (widest === -1)
+            break;
+        widths[widest] = widths[widest] - 1;
+        total -= 1;
+    }
+    const line = (cells) => cells
+        .map((cell, index) => truncate(cell, widths[index]).padEnd(widths[index]))
+        .join(" ".repeat(gutter))
+        .trimEnd();
+    return [line(headers), line(widths.map((width) => "-".repeat(width))), ...rows.map(line)].join("\n");
+}
+export const FOLLOW_UP_MARKER = "[FOLLOW_UPS:";
+/**
+ * The /ask answer carries a trailing `[FOLLOW_UPS: "a" | "b"]` marker meant for
+ * the site chat UI. Split it off so stdout stays readable prose.
+ *
+ * The closing bracket is optional on purpose: the API truncates `answer` to a
+ * fixed length, so a long reply arrives with the marker cut off mid-word and no
+ * `]` at all (verified against production 2026-08-21). Anchoring on the bracket
+ * would leak the fragment into the output in exactly the common case.
+ */
+export function splitFollowUps(answer) {
+    const index = answer.indexOf(FOLLOW_UP_MARKER);
+    if (index === -1)
+        return { text: answer.trim(), followUps: [] };
+    const rest = answer.slice(index + FOLLOW_UP_MARKER.length);
+    const close = rest.indexOf("]");
+    const body = close === -1 ? rest : rest.slice(0, close);
+    const followUps = body
+        .split("|")
+        .map((entry) => entry.trim().replace(/^"|"$/g, "").trim())
+        // A truncated marker ends in a partial, unquoted entry. Keeping it would
+        // print half a sentence as if it were a real suggestion.
+        .filter((entry, position, all) => {
+        if (entry.length === 0)
+            return false;
+        const isLast = position === all.length - 1;
+        return !(isLast && close === -1);
+    });
+    return { text: answer.slice(0, index).trim(), followUps };
+}
+/**
+ * Streaming counterpart: /api/chat emits the same marker, but a chunk boundary
+ * can fall inside it. This holds back any tail that could still turn out to be
+ * the start of the marker, so the filter never emits a partial `[FOLLOW`.
+ */
+export function createTrailerStripper() {
+    let held = "";
+    let finished = false;
+    return {
+        push(chunk) {
+            if (finished)
+                return "";
+            held += chunk;
+            const index = held.indexOf(FOLLOW_UP_MARKER);
+            if (index !== -1) {
+                // Nothing more will be emitted, so the blank line that separated the
+                // prose from the marker would just be trailing whitespace. Drop it, to
+                // match what splitFollowUps does on the non-streaming path.
+                const emitted = held.slice(0, index).replace(/\s+$/, "");
+                held = "";
+                finished = true;
+                return emitted;
+            }
+            // Longest suffix of the buffer that is also a prefix of the marker.
+            let keep = 0;
+            const max = Math.min(held.length, FOLLOW_UP_MARKER.length - 1);
+            for (let size = max; size > 0; size--) {
+                if (held.endsWith(FOLLOW_UP_MARKER.slice(0, size))) {
+                    keep = size;
+                    break;
+                }
+            }
+            let holdFrom = held.length - keep;
+            // Hold the whitespace in front of a candidate marker too. If it does turn
+            // out to be the marker, that whitespace is the blank line separating the
+            // prose from it, and by then it is too late to unprint.
+            if (keep > 0) {
+                while (holdFrom > 0 && /\s/.test(held[holdFrom - 1]))
+                    holdFrom--;
+            }
+            const emitted = held.slice(0, holdFrom);
+            held = held.slice(holdFrom);
+            return emitted;
+        },
+        flush() {
+            if (finished)
+                return "";
+            const remaining = held;
+            held = "";
+            finished = true;
+            return remaining;
+        },
+    };
+}
+export function indentList(items) {
+    return items.map((item) => `  - ${item}`).join("\n");
+}

package/dist/http.js

@@ -0,0 +1,175 @@
+import { CliError, usageError } from "./errors.js";
+export const DEFAULT_BASE_URL = "https://yonyon.ai";
+/** LLM-backed endpoints think for a while; the flat JSON ones should not. */
+export const SLOW_TIMEOUT_MS = 60_000;
+export const FAST_TIMEOUT_MS = 15_000;
+/** Normalize and validate a base URL so a typo fails here, not mid-request. */
+export function resolveBaseUrl(raw) {
+    const candidate = raw ?? process.env["YONYON_BASE_URL"] ?? DEFAULT_BASE_URL;
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        throw usageError(`--base-url must be an absolute URL, got "${candidate}".`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw usageError(`--base-url must be http or https, got "${parsed.protocol}".`);
+    }
+    return parsed.origin + parsed.pathname.replace(/\/$/, "");
+}
+function describeRateLimit(response) {
+    const limit = response.headers.get("x-ratelimit-limit");
+    const retryAfter = response.headers.get("retry-after");
+    const ceiling = limit ? `${limit} requests per IP per minute` : "10 requests per IP per minute";
+    const wait = retryAfter ? ` Retry in ${retryAfter}s.` : "";
+    return new CliError(`Rate limited by yonyon.ai (${ceiling}).${wait}`, {
+        hints: [
+            "The public API is unauthenticated, so the budget is shared per source IP.",
+            "Wait for the window to reset and run the command again.",
+        ],
+    });
+}
+/**
+ * Reduce a non-JSON error body to one useful line.
+ *
+ * Returns "" when the body is markup with nothing quotable, because the status
+ * line alone reads better than a wall of HTML.
+ */
+export function summariseNonJsonBody(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return "";
+    const looksLikeHtml = /^\s*(<!doctype|<html|<\?xml)/i.test(trimmed);
+    if (looksLikeHtml) {
+        const title = /<title[^>]*>([^<]{1,200})<\/title>/i.exec(trimmed)?.[1]?.trim();
+        return title ? title.replace(/\s+/g, " ") : "";
+    }
+    // Plain text, so it is probably already the message. Collapse whitespace so a
+    // multi-line body does not smear across the terminal.
+    const oneLine = trimmed.replace(/\s+/g, " ");
+    return oneLine.length > 200 ? `${oneLine.slice(0, 200)}...` : oneLine;
+}
+/** Pull the most useful message out of an error body, whatever shape it has. */
+async function describeFailure(response, url) {
+    if (response.status === 429)
+        return describeRateLimit(response);
+    let detail = "";
+    try {
+        const text = await response.text();
+        if (text) {
+            try {
+                const body = JSON.parse(text);
+                if (body !== null && typeof body === "object") {
+                    const record = body;
+                    const message = record["error"] ?? record["message"];
+                    const code = record["code"];
+                    if (typeof message === "string")
+                        detail = message;
+                    if (typeof code === "string")
+                        detail = detail ? `${detail} (${code})` : code;
+                }
+            }
+            catch {
+                // Not JSON. An HTML error page is the common case here (a wrong
+                // --base-url lands on the site's 404 page, not the API), and echoing
+                // 300 characters of `<!DOCTYPE html><html lang="en"...` into the
+                // terminal buries the one line that matters. Prefer the <title>, and
+                // otherwise say nothing rather than paste markup.
+                detail = summariseNonJsonBody(text);
+            }
+        }
+    }
+    catch {
+        // A body we cannot read is not more informative than the status line.
+    }
+    const suffix = detail ? `: ${detail}` : "";
+    return new CliError(`Request to ${url} failed with HTTP ${response.status}${suffix}`);
+}
+/** Turn fetch's opaque failures into something a human can act on. */
+function describeNetworkFailure(error, url, timeoutMs) {
+    if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) {
+        return new CliError(`Request to ${url} timed out after ${timeoutMs}ms.`, {
+            hints: ["Raise the ceiling with --timeout <ms>, or retry."],
+        });
+    }
+    const reason = error instanceof Error ? error.message : String(error);
+    return new CliError(`Could not reach ${url}: ${reason}`, {
+        hints: ["Check your network connection, or point elsewhere with --base-url."],
+    });
+}
+async function send(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        throw describeNetworkFailure(error, url, timeoutMs);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function getJson(ctx, path) {
+    const url = `${ctx.baseUrl}${path}`;
+    const response = await send(url, { headers: { accept: "application/json" } }, ctx.timeoutMs);
+    if (!response.ok)
+        throw await describeFailure(response, url);
+    return (await response.json());
+}
+export async function postJson(ctx, path, body, extraHeaders = {}) {
+    const url = `${ctx.baseUrl}${path}`;
+    const response = await send(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json", ...extraHeaders },
+        body: JSON.stringify(body),
+    }, ctx.timeoutMs);
+    if (!response.ok)
+        throw await describeFailure(response, url);
+    return (await response.json());
+}
+/**
+ * POST and stream the text body back chunk by chunk.
+ *
+ * `/api/chat` enforces a CSRF check that rejects any request without an
+ * `Origin` header whose host matches the request host (verified 2026-08-21: a
+ * bare POST returns HTTP 403 `{"error":"Forbidden","code":"forbidden"}`). We
+ * send the base URL as the Origin so the CLI is a first-class caller rather
+ * than a blocked one. Callers that only need one answer should use /ask.
+ */
+export async function postStream(ctx, path, body, onChunk) {
+    const url = `${ctx.baseUrl}${path}`;
+    const response = await send(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "text/plain",
+            origin: ctx.baseUrl,
+        },
+        body: JSON.stringify(body),
+    }, ctx.timeoutMs);
+    if (!response.ok)
+        throw await describeFailure(response, url);
+    if (!response.body) {
+        onChunk(await response.text());
+        return;
+    }
+    const decoder = new TextDecoder();
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                onChunk(decoder.decode(value, { stream: true }));
+        }
+        const tail = decoder.decode();
+        if (tail)
+            onChunk(tail);
+    }
+    catch (error) {
+        throw describeNetworkFailure(error, url, ctx.timeoutMs);
+    }
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+process.exitCode = await run(process.argv.slice(2));

package/dist/io.js

@@ -0,0 +1,9 @@
+export const processIo = {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+    isTty: Boolean(process.stdout.isTTY),
+};
+/** Convenience: write a line to stdout. */
+export function line(io, text = "") {
+    io.out(`${text}\n`);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "yonyon",
+  "version": "0.1.0",
+  "description": "Command line client for the public yonyon.ai agent API. Ask questions, list projects, wire up the MCP server, book an intro call. No auth, no config.",
+  "type": "module",
+  "bin": {
+    "yonyon": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "author": "Yonatan Gross <yonaigross@gmail.com> (https://yonyon.ai)",
+  "homepage": "https://yonyon.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yonatan-HQ/portfolio.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Yonatan-HQ/portfolio/issues"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "agent",
+    "agents",
+    "llm",
+    "cli",
+    "model-context-protocol",
+    "yonyon",
+    "agent-readiness",
+    "nlweb"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}