pyyol 1.13.0 → 1.14.1

package/dist/cli.js

@@ -19,6 +19,7 @@ import { deriveConnectUrl, deviceLabel, runLoginFlow } from "./login.js";
 import * as mode from "./mode.js";
 import { RuntimeConnector } from "./runtime.js";
 import { askWatch, watchUrl, WATCH_BROWSER, WATCH_TERMINAL } from "./watch.js";
+import { INTENT_INVITE, friendsUrl, isInsufficientBalance, offerBuyCoins, resolveStartupIntent, } from "./intent.js";
 import { REQUEST_ID_HEADER, SIGNATURE_HEADER, SIGNATURE_VERSION, TIMESTAMP_HEADER, computeSignature, } from "./signing.js";
 import { SDK_VERSION } from "./version.js";
 const OK = "✓";
@@ -560,9 +561,44 @@ async function orchestrate(a, devLocked) {
         // agent key can't expire, so refresh is only wired when NOT using it.
         ...(usingAgentKey ? {} : refreshOpts(c, base)),
     });
+    // Join vs Invite — only on `pyyol play` (not `dev`). Non-TTY / --queue / --ranked
+    // keep today's auto-start so CI and scripts never hang on a prompt.
+    let startup = "queue";
+    if (!devLocked) {
+        const tty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        startup = await resolveStartupIntent({
+            ranked: m === mode.RANKED || bool(a, "ranked"),
+            mode: str(a, "mode") || null,
+            queueFlag: bool(a, "queue"),
+            inviteFlag: bool(a, "invite"),
+            isTty: tty,
+        });
+        if (startup === INTENT_INVITE) {
+            const dash = (str(a, "dashboard") || DEFAULT_DASHBOARD).replace(/\/$/, "");
+            const url = friendsUrl(dash);
+            console.log(`  ${OK} invite mode — connected; not queueing a match`);
+            if (url) {
+                console.log(`  ${OK} invite a friend: ${url}`);
+                const openMode = str(a, "open") || "auto";
+                if (openMode !== "never" && tty) {
+                    try {
+                        const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+                        spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+                        console.log(`  ${OK} opened Play a friend in your browser`);
+                    }
+                    catch {
+                        /* link already printed */
+                    }
+                }
+            }
+        }
+    }
     // Kick match(es) after the socket registers; retry while it comes online.
+    // Invite mode stays connected only — the developer hosts from /friends.
     const matches = num(a, "matches", devLocked ? 3 : 1);
     setTimeout(async () => {
+        if (!devLocked && startup === INTENT_INVITE)
+            return;
         if (m === mode.RANKED) {
             const tier = str(a, "tier") || "low";
             const [st, resp] = await enqueueRanked(base, token, arena, { game: arena, tier }, {
@@ -573,6 +609,10 @@ async function orchestrate(a, devLocked) {
                 console.log(`  ${OK} queued for RANKED ${arena} (tier ${tier})`);
             else if (rankedUnreachable(resp))
                 console.log(`  ${BAD} this agent is not reachable for ranked — keep \`pyyol play\` / \`pyyol dev\` connected, or publish a hosted endpoint to play while away.`);
+            else if (isInsufficientBalance(resp, { status: st })) {
+                const dash = (str(a, "dashboard") || DEFAULT_DASHBOARD).replace(/\/$/, "");
+                offerBuyCoins(dash);
+            }
             else
                 console.log(`  ${BAD} could not queue ranked (${st}): ${JSON.stringify(resp)}`);
             return;
@@ -778,8 +818,10 @@ async function cmdQueue(a) {
         const code = String(resp.code ?? resp.error ?? "");
         if (code.includes("certified") || code.includes("playable") || code.includes("not_connected"))
             console.error(`${BAD} this agent is not reachable for ranked. Keep it connected (\`pyyol play\` / \`pyyol dev\`), or publish a hosted endpoint to play while away.`);
-        else if (code.includes("balance") || code.includes("insufficient"))
-            console.error(`${BAD} not enough coins — fund your wallet (see \`pyyol wallet\`).`);
+        else if (isInsufficientBalance(resp, { status: st, code })) {
+            const dash = (str(a, "dashboard") || DEFAULT_DASHBOARD).replace(/\/$/, "");
+            offerBuyCoins(dash);
+        }
         else
             console.error(`${BAD} could not queue ranked (${st}): ${JSON.stringify(resp)}`);
         return 1;
@@ -789,10 +831,13 @@ async function cmdQueue(a) {
         console.log(`  ${OK} matched → ${resp.match_id}\n      watch it:  pyyol watch ${resp.match_id}`);
     return 0;
 }
-/** `pyyol room create|join [id] [--tier low|mid|high | --bid N]` — a PRIVATE staked table.
+/** `pyyol room create|join [id] [--tier low|mid|high | --bid N] [--game goofspiel|mafia]` — a PRIVATE staked table.
  *
- * The queue supplies whoever is waiting. A room is for the other case: two developers who
- * want THEIR two agents to play each other. One creates it, sends the id, the other joins.
+ * The queue supplies whoever is waiting. A room is for the other case: developers who
+ * want THEIR agents to play each other. One creates it, sends the id, the other joins.
+ *
+ * - goofspiel (default): 1v1 private waiting match.
+ * - mafia: 12 seats — invited agents only; no house-bot fill. Match starts when full.
  *
  * Deliberately the same match as everywhere else: same stake path, same escrow, same
  * refusal to seat both sides on one account. The sit gate is the same live path as
@@ -810,7 +855,7 @@ async function cmdRoom(a) {
     }
     const action = a.positionals[0] ?? "";
     if (action !== "create" && action !== "join") {
-        console.error(`${BAD} usage: pyyol room create [--tier low|mid|high | --bid N]`);
+        console.error(`${BAD} usage: pyyol room create [--tier low|mid|high | --bid N] [--game goofspiel|mafia]`);
         console.error(`         pyyol room join <room-id>`);
         return 2;
     }
@@ -830,37 +875,45 @@ async function cmdRoom(a) {
         }
         const [st, resp] = await apiPost(`${base}/v1/lobby/join`, token, { match_id: id });
         if (st !== 200)
-            return roomError(st, resp, "join");
+            return roomError(st, resp, "join", str(a, "dashboard") || "");
         console.log(`${OK} joined room ${id}`);
         console.log("    keep your agent connected (`pyyol play`) — it plays automatically.");
         console.log(`    watch it:  pyyol watch ${id}`);
         return 0;
     }
-    const body = {};
+    const game = (str(a, "game") || "goofspiel").toLowerCase();
+    if (game !== "goofspiel" && game !== "mafia") {
+        console.error(`${BAD} private rooms support goofspiel (1v1) and mafia (12 seats: invited agents only, no house bots).`);
+        return 2;
+    }
+    const body = { game };
     if (str(a, "tier"))
         body.tier = str(a, "tier");
     else if (num(a, "bid", 0) > 0)
         body.bid = num(a, "bid", 0);
     else {
         console.error(`${BAD} a room is staked: pass --tier <low|mid|high> ` +
-            `(see \`pyyol queue goofspiel --list\`) or --bid <coins>.`);
+            `(see \`pyyol queue ${game} --list\`) or --bid <coins>.`);
         return 2;
     }
     const [st, resp] = await apiPost(`${base}/v1/room/create`, token, body);
     if (st !== 200 && st !== 201)
-        return roomError(st, resp, "create");
+        return roomError(st, resp, "create", str(a, "dashboard") || "");
     const roomId = String(resp.room_id ?? resp.match_id ?? "");
     console.log(`${OK} room created`);
     if (resp.bid)
         console.log(`    stake: ${resp.bid} coins each`);
+    if (game === "mafia") {
+        console.log("    mafia: 12 seats — invited agents only (no house bots); starts when full");
+    }
     // The id gets its own line with nothing around it, because the next thing anyone does is
     // drag-select it to paste into a chat, and a line with prose on it selects badly.
     console.log();
     console.log(`    ${roomId}`);
     console.log();
-    console.log("    send that to the other player. they run:");
+    console.log("    send that to the other players. they run:");
     console.log(`        pyyol room join ${roomId}`);
-    console.log("    keep your agent connected (`pyyol play`) — it plays as soon as they join.");
+    console.log("    keep your agent connected (`pyyol play`) — it plays when the table is full.");
     return 0;
 }
 /** Turn the arena's refusal codes into something a developer can act on.
@@ -869,7 +922,7 @@ async function cmdRoom(a) {
  * never what to do about it, which on a staked action is the difference between a retry and
  * giving up.
  */
-function roomError(st, resp, what) {
+function roomError(st, resp, what, dashboard = "") {
     const code = String(resp.code ?? resp.error ?? "");
     const msg = resp.message ?? "";
     if (code.includes("same_owner")) {
@@ -881,8 +934,8 @@ function roomError(st, resp, what) {
             `then open the room. A hosted deploy also works. Auto-play alone is not a play path. ` +
             `Private rooms do not need ranked endpoint verification.`);
     }
-    else if (code.includes("balance") || code.includes("insufficient")) {
-        console.error(`${BAD} not enough coins to stake this room.`);
+    else if (isInsufficientBalance(resp, { status: st, code })) {
+        offerBuyCoins((dashboard || DEFAULT_DASHBOARD).replace(/\/$/, ""));
     }
     else if (code.includes("not_found")) {
         console.error(`${BAD} no such room — check the id, or it may have been cancelled.`);
@@ -1834,10 +1887,10 @@ Commands:
   whoami
   init <dir> [--arena goofspiel|mafia] [--framework F] [--name N]
   dev [--matches N]                 local dev loop — SANDBOX, no stakes
-  play <arena> [--ranked] [--tier]  compete; --ranked = real stakes
+  play <arena> [--ranked] [--tier] [--queue|--invite|--mode]  compete; Join vs Invite on TTY
   publish --manifest <file>         optional: verify a hosted endpoint to play ranked while away
   queue <game> [--tier low|mid|high | --bid N] [--list]  enter ranked matchmaking
-  room create [--tier low|mid|high | --bid N]      open a PRIVATE staked table
+  room create [--tier … | --bid N] [--game goofspiel|mafia]  private invite table (Mafia: 12 invited agents, no bots)
   room join <room-id>               play a specific opponent by their room id
   wallet [--json]                   your coin balance + per-agent wallets
   replay <match_id> [--game] [--json]

package/dist/intent.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Join vs Invite for `pyyol play` — mirrors `pyyol/console.py::ask_intent`.
+ *
+ * Same three rules as askWatch: never blocks a machine, never outlives the
+ * countdown, never eats the agent's turn. Timeout defaults to Join so CI and
+ * scripts that somehow hit a TTY still queue.
+ */
+export declare const INTENT_QUEUE = "queue";
+export declare const INTENT_INVITE = "invite";
+export type StartupIntent = typeof INTENT_QUEUE | typeof INTENT_INVITE;
+export interface AskIntentOpts {
+    timeoutMs?: number;
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    color?: boolean;
+}
+/** Absolute Play-a-friend URL. Empty dashboard → no invented public link. */
+export declare function friendsUrl(dashboard?: string | null | undefined): string;
+/** Absolute Buy-coins wallet URL (`/wallet?tab=buy`). Empty dashboard → no link. */
+export declare function walletBuyUrl(dashboard?: string | null | undefined): string;
+/** Normalize arena error envelopes to a lowercase code string. */
+export declare function apiErrorCode(resp: unknown): string;
+/** True for HTTP 402 / `insufficient_balance` from CheckJoin and stake sits. */
+export declare function isInsufficientBalance(resp?: unknown, opts?: {
+    status?: number;
+    code?: string;
+}): boolean;
+export interface OfferBuyCoinsOpts {
+    openBrowser?: boolean;
+    stdout?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    color?: boolean;
+    isTty?: boolean;
+    /** Injected opener for tests. Defaults to platform `open` / `xdg-open` / `start`. */
+    opener?: (url: string) => boolean | void;
+}
+/**
+ * Print a professional funds prompt for a refused paid sit; optionally open Buy coins.
+ * Never waits for input — non-TTY / CI only print the URL. Returns the URL (may be empty).
+ */
+export declare function offerBuyCoins(dashboard?: string | null | undefined, opts?: OfferBuyCoinsOpts): string;
+export declare function askIntent(opts?: AskIntentOpts): Promise<StartupIntent>;
+export interface ResolveStartupIntentOpts {
+    ranked?: boolean;
+    mode?: string | null;
+    queueFlag?: boolean;
+    inviteFlag?: boolean;
+    env?: Record<string, string | undefined>;
+    isTty?: boolean;
+    ask?: (opts?: AskIntentOpts) => Promise<StartupIntent>;
+    askTimeoutMs?: number;
+}
+/** Decide queue vs invite for `pyyol play` (not `dev` / `run`). */
+export declare function resolveStartupIntent(opts?: ResolveStartupIntentOpts): Promise<StartupIntent>;

package/dist/intent.js

@@ -0,0 +1,160 @@
+/**
+ * Join vs Invite for `pyyol play` — mirrors `pyyol/console.py::ask_intent`.
+ *
+ * Same three rules as askWatch: never blocks a machine, never outlives the
+ * countdown, never eats the agent's turn. Timeout defaults to Join so CI and
+ * scripts that somehow hit a TTY still queue.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { DEFAULT_DASHBOARD } from "./watch.js";
+export const INTENT_QUEUE = "queue";
+export const INTENT_INVITE = "invite";
+// eslint-disable-next-line no-control-regex -- matching them is the point
+const ANSI = /\x1b\[[0-9;]*m/g;
+const visibleLen = (s) => s.replace(ANSI, "").length;
+/** Absolute Play-a-friend URL. Empty dashboard → no invented public link. */
+export function friendsUrl(dashboard = DEFAULT_DASHBOARD) {
+    const base = (dashboard ?? "").replace(/\/$/, "");
+    return base ? `${base}/friends` : "";
+}
+/** Absolute Buy-coins wallet URL (`/wallet?tab=buy`). Empty dashboard → no link. */
+export function walletBuyUrl(dashboard = DEFAULT_DASHBOARD) {
+    const base = (dashboard ?? "").replace(/\/$/, "");
+    return base ? `${base}/wallet?tab=buy` : "";
+}
+/** Normalize arena error envelopes to a lowercase code string. */
+export function apiErrorCode(resp) {
+    if (!resp || typeof resp !== "object")
+        return String(resp ?? "").toLowerCase();
+    const r = resp;
+    if (typeof r.code === "string" && r.code.trim())
+        return r.code.trim().toLowerCase();
+    const err = r.error;
+    if (err && typeof err === "object" && typeof err.code === "string") {
+        return String(err.code).trim().toLowerCase();
+    }
+    if (typeof err === "string")
+        return err.trim().toLowerCase();
+    return "";
+}
+/** True for HTTP 402 / `insufficient_balance` from CheckJoin and stake sits. */
+export function isInsufficientBalance(resp, opts = {}) {
+    if (opts.status === 402)
+        return true;
+    const c = (opts.code || "").trim().toLowerCase() || apiErrorCode(resp);
+    if (!c)
+        return false;
+    return c === "insufficient_balance" || (c.includes("insufficient") && c.includes("balance"));
+}
+/**
+ * Print a professional funds prompt for a refused paid sit; optionally open Buy coins.
+ * Never waits for input — non-TTY / CI only print the URL. Returns the URL (may be empty).
+ */
+export function offerBuyCoins(dashboard = DEFAULT_DASHBOARD, opts = {}) {
+    const out = opts.stdout ?? process.stderr;
+    const url = walletBuyUrl(dashboard);
+    const tty = opts.isTty ?? Boolean(out.isTTY);
+    const color = opts.color ?? (process.env.NO_COLOR === undefined && tty);
+    const c = (text, code) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+    const rows = [
+        c("not enough coins to cover this stake", "1"),
+        "",
+        c("Buy coins (or allocate to this agent), then retry.", "90"),
+    ];
+    const width = Math.max(...rows.map(visibleLen)) + 2;
+    out.write("\n" + c("╭─ pyyol " + "─".repeat(Math.max(0, width - 7)) + "╮", "90") + "\n");
+    for (const r of rows) {
+        out.write(c("│", "90") + " " + r + " ".repeat(width - visibleLen(r)) + c("│", "90") + "\n");
+    }
+    out.write(c("╰" + "─".repeat(width + 1) + "╯", "90") + "\n");
+    if (url)
+        out.write("  " + c(url, "36") + "\n");
+    if (url && (opts.openBrowser ?? true) && tty) {
+        try {
+            let opened = false;
+            if (opts.opener) {
+                opened = Boolean(opts.opener(url));
+            }
+            else {
+                const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+                spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+                opened = true;
+            }
+            if (opened)
+                out.write("  " + c("opened Buy coins in your browser", "32") + "\n");
+        }
+        catch {
+            /* URL already printed */
+        }
+    }
+    return url;
+}
+export async function askIntent(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY)
+        return INTENT_QUEUE;
+    const color = opts.color ?? process.env.NO_COLOR === undefined;
+    const c = (text, code) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+    const rows = [
+        c("how should this agent play?", "36"),
+        "",
+        `${c("[j]", "1")} Join a game                   ${c("· default", "90")}`,
+        `${c("[i]", "1")} Invite a friend`,
+    ];
+    const width = Math.max(...rows.map(visibleLen)) + 2;
+    stdout.write("\n" + c("╭─ pyyol play " + "─".repeat(Math.max(0, width - 12)) + "╮", "90") + "\n");
+    for (const r of rows) {
+        stdout.write(c("│", "90") + " " + r + " ".repeat(width - visibleLen(r)) + c("│", "90") + "\n");
+    }
+    stdout.write(c("╰" + "─".repeat(width + 1) + "╯", "90") + "\n");
+    stdout.write("  " + c("›", "36") + " ");
+    const answer = await readLine(stdin, timeoutMs);
+    if (answer === null) {
+        stdout.write("\n  " + c(`no answer in ${Math.round(timeoutMs / 1000)}s — joining a game`, "90") + "\n");
+        return INTENT_QUEUE;
+    }
+    return answer.trim().toLowerCase().startsWith("i") ? INTENT_INVITE : INTENT_QUEUE;
+}
+/** Decide queue vs invite for `pyyol play` (not `dev` / `run`). */
+export async function resolveStartupIntent(opts = {}) {
+    if (opts.ranked || opts.queueFlag)
+        return INTENT_QUEUE;
+    if (opts.inviteFlag)
+        return INTENT_INVITE;
+    const m = (opts.mode || "").trim().toLowerCase();
+    if (m === "queue")
+        return INTENT_QUEUE;
+    if (m === "invite")
+        return INTENT_INVITE;
+    const envMap = opts.env ?? process.env;
+    const envV = (envMap.PYYOL_STARTUP || "").trim().toLowerCase();
+    if (envV === INTENT_QUEUE || envV === INTENT_INVITE)
+        return envV;
+    if (!opts.isTty)
+        return INTENT_QUEUE;
+    const asker = opts.ask ?? askIntent;
+    return asker({ timeoutMs: opts.askTimeoutMs });
+}
+function readLine(stdin, timeoutMs) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: stdin });
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            rl.close();
+            if (typeof stdin.pause === "function")
+                stdin.pause();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        rl.once("line", (line) => finish(line));
+        rl.once("close", () => finish(null));
+        rl.once("error", () => finish(null));
+    });
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.13.0";
+export declare const SDK_VERSION = "1.14.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // GENERATED by scripts/genversion.mjs — do not edit by hand.
 // Source of truth is the "version" field in package.json.
-export const SDK_VERSION = "1.13.0"; // x-release-please-version
+export const SDK_VERSION = "1.14.1"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
   "type": "module",
   "main": "dist/index.js",

package/rules/llms-full.txt

@@ -33,8 +33,12 @@ pyyol                             # the front door — everything runs from here
   <img src="assets/cli-home.svg" alt="The pyyol home screen" width="720">
 </p>
 
-Press `/` for the command menu — grouped by what you actually do, filter by typing,
-Enter to run. Everything below works inside it, or as a plain command if you prefer:
+Press `/` at the Python prompt for the command menu — grouped by what you actually do,
+filter by typing, Enter to run. **`/` is a key, not a line:** you do not press Enter
+first. Everything below works inside it, or as a plain command if you prefer.
+
+From bash, `pyyol help` and `pyyol /help` print the same list; `pyyol help play` shows
+flags. The JS CLI has no interactive shell — run commands directly (`npx pyyol help`).
 
 ```bash
 pyyol login                       # browser login (GitHub / Google / wallet / email)
@@ -119,8 +123,9 @@ happy, compete:
 
 ```bash
 pyyol play goofspiel                     # compete in SANDBOX (no stakes)
-pyyol publish --manifest manifest.json   # certify your agent for ranked (one-time)
-pyyol play goofspiel --ranked            # compete for REAL — explicit, confirmed
+pyyol play goofspiel --ranked            # compete for REAL — keep this process connected
+# optional, only if you want the agent to play while you are away:
+# pyyol publish --manifest manifest.json
 ```
 
 ---
@@ -158,13 +163,14 @@ The one rule that matters: **you can never lose money by accident.**
 | | `pyyol dev` | `pyyol play <arena>` | `pyyol play <arena> --ranked` |
 |---|---|---|---|
 | Stakes | never | none (sandbox) | **real** (escrow · Elo · P-Index) |
-| Certification | not needed | not needed | required (`pyyol publish`) |
+| Certification | not needed | not needed | not needed if `pyyol play` is connected; hosted verify is the away path |
 | Confirmation | — | — | one-time `y/N` (skip with `--yes` in CI) |
 
 - **`pyyol dev`** is hard-locked to sandbox — development can never touch stakes.
 - **`pyyol play <arena>`** defaults to sandbox. Real stakes require the explicit
-  `--ranked` flag, a certified agent, and a confirmation. Every run prints a banner
-  (`● SANDBOX` / `⚠ RANKED`) so you always know where you are.
+  `--ranked` flag, a connected agent (or a hosted verified endpoint if you are away),
+  and a confirmation. Every run prints a banner (`● SANDBOX` / `⚠ RANKED`) so you
+  always know where you are.
 - Mode can also come from `PYYOL_MODE` or `pyyol.toml`, but `--ranked` is always the
   clearest signal. Precedence: `--ranked` > `PYYOL_MODE` > `pyyol.toml` > sandbox.
 
@@ -198,7 +204,7 @@ entry = "agent.py:agent"  # module:variable the SDK loads
 | `pyyol init <dir>` | Scaffold an agent + `pyyol.toml`. |
 | `pyyol dev` | Local dev loop — SANDBOX practice, never stakes. |
 | `pyyol play <arena>` | Compete. Sandbox by default; `--ranked` for real. |
-| `pyyol publish --manifest <file>` | Certify your agent for ranked (verify a hosted endpoint). `--manifest` is required. |
+| `pyyol publish --manifest <file>` | Optional. Verify a hosted endpoint so the agent can play ranked while you are away. |
 | `pyyol replay <id>` | Fetch a match replay. |
 | `pyyol profile [@handle]` | Developer profile + P-Index (self if omitted). |
 | `pyyol leaderboard [--game G] [--developers]` | Leaderboards. |
@@ -250,7 +256,7 @@ See the full guide at `/v1/docs → "Verified LLM agents"` (and `examples/llm_ag
 
 # CLI reference
 
-Generated from `pyyol` v1.10.1. Every command below is real — this page is
+Generated from `pyyol` v1.14.0. Every command below is real — this page is
 produced from the parser the CLI dispatches through, so it cannot list a command that
 does not exist or miss one that does.
 
@@ -268,8 +274,8 @@ pyyol
   <img src="assets/cli-home.svg" alt="The pyyol home screen: wordmark, version, sign-in state and the affordance line" width="760">
 </p>
 
-Press `/` and the command menu opens — grouped by what you actually do, most-used
-first, filter by typing, Enter to run:
+At the prompt, press `/` — that is a key, not a line to submit. The command menu
+opens immediately (no Enter). Arrow to move, type to filter, Enter to run:
 
 <p align="center">
   <img src="assets/cli-menu.svg" alt="The pyyol / command menu, grouped into PLAY, SHIP and INSPECT" width="760">
@@ -280,13 +286,15 @@ when the tool does.
 
 ### Inside the shell
 
-- `/` opens the picker. Arrow to move, type to filter — the filter matches the
-  DESCRIPTION as well as the name, so "stake" finds `play` and "coins" finds
-  `wallet`. Enter runs it.
+- `/` opens the picker **on the keystroke** — do not press Enter first. Arrow to move,
+  type to filter — the filter matches the DESCRIPTION as well as the name, so "stake"
+  finds `play` and "coins" finds `wallet`. Enter runs it.
+- `help` (or `/help` from bash) lists every command. `help play` shows that command's flags.
 - Long lists scroll and a counter shows your position, so every command is reachable.
 - Every command below works inside it, with or without the leading slash, and flags
-  pass straight through: `/play mafia --ranked`.
+  pass straight through: `play mafia --ranked`.
 - `tab` completes, `Ctrl-C` stops the running command (not the session), `/exit` leaves.
+- From bash, `pyyol /help` and `pyyol /play …` work too — a leading slash is stripped.
 
 **Not on a terminal, no prompt.** Piped, in CI, in cron or in a Dockerfile `RUN`,
 `pyyol` prints this help and exits — a prompt waiting on stdin there would hang the
@@ -302,8 +310,9 @@ compete in an arena. SANDBOX by default; --ranked = real stakes
 
 ```
 usage: pyyol play [-h] [--ranked] [--tier TIER] [--matches MATCHES] [--yes]
-                  [--url URL] [--agent AGENT] [--token TOKEN] [--quiet]
-                  [--no-color] [--open {auto,always,never}] [--api API]
+                  [--mode {queue,invite,ask}] [--queue] [--invite] [--url URL]
+                  [--agent AGENT] [--token TOKEN] [--quiet] [--no-color]
+                  [--open {auto,always,never}] [--api API]
                   [--watch {ask,browser,terminal}]
                   {goofspiel,mafia}
 
@@ -312,22 +321,27 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  --ranked              REAL stakes (needs `pyyol publish`; confirmed)
+  --ranked              REAL stakes (connected CLI is enough; hosted verify is the away
+                        path)
   --tier TIER           ranked stake tier: low|mid|high
-  --matches MATCHES     sandbox matches to start
+  --matches MATCHES     sandbox matches to start (0 = connect only)
   --yes                 skip the ranked confirmation (CI)
+  --mode {queue,invite,ask}
+                        after connect: queue (join), invite (friends, no queue), or ask
+                        (TTY)
+  --queue               join a game (skip Join/Invite prompt; same as --mode=queue)
+  --invite              invite a friend: connect only + open /friends (no queue)
   --url URL
   --agent AGENT
   --token TOKEN
   --quiet
   --no-color
   --open {auto,always,never}
-                        open the live match in your browser: auto (first only)
-                        | always | never
+                        open the live match in your browser: auto (first only) | always
+                        | never
   --api API             platform API base (defaults to the logged-in one)
   --watch {ask,browser,terminal}
-                        where to watch a match: ask (default) | browser |
-                        terminal
+                        where to watch a match: ask (default) | browser | terminal
 ```
 
 ### `pyyol dev`
@@ -335,10 +349,9 @@ options:
 run your agent locally in SANDBOX (no stakes) — the dev loop
 
 ```
-usage: pyyol dev [-h] [--matches MATCHES] [--url URL] [--agent AGENT]
-                 [--token TOKEN] [--quiet] [--no-color]
-                 [--open {auto,always,never}] [--watch {ask,browser,terminal}]
-                 [--api API]
+usage: pyyol dev [-h] [--matches MATCHES] [--url URL] [--agent AGENT] [--token TOKEN]
+                 [--quiet] [--no-color] [--open {auto,always,never}]
+                 [--watch {ask,browser,terminal}] [--api API]
 
 options:
   -h, --help            show this help message and exit
@@ -349,11 +362,10 @@ options:
   --quiet
   --no-color
   --open {auto,always,never}
-                        open the live match in your browser: auto (first only)
-                        | always | never
+                        open the live match in your browser: auto (first only) | always
+                        | never
   --watch {ask,browser,terminal}
-                        where to watch a match: ask (default) | browser |
-                        terminal
+                        where to watch a match: ask (default) | browser | terminal
   --api API             platform API base (defaults to the logged-in one)
 ```
 
@@ -391,7 +403,7 @@ options:
 enter ranked matchmaking at a stake tier (your connected agent plays)
 
 ```
-usage: pyyol queue [-h] [--api API] [--list] [--tier TIER] [--bid BID]
+usage: pyyol queue [-h] [--api API] [--list] [--tier TIER] [--bid BID] [--wait WAIT]
                    [--token TOKEN]
                    game
 
@@ -404,6 +416,32 @@ options:
   --list         show the game's stake tiers and exit
   --tier TIER    stake tier key (see --list)
   --bid BID      explicit coin stake for a tier-less game
+  --wait WAIT    seconds to wait for a pairing before returning (the agent plays
+                 regardless)
+  --token TOKEN
+```
+
+### `pyyol room`
+
+create or join a private staked invite table (goofspiel or mafia)
+
+```
+usage: pyyol room [-h] [--api API] [--game {goofspiel,mafia}] [--tier TIER] [--bid BID]
+                  [--token TOKEN]
+                  {create,join} [id]
+
+positional arguments:
+  {create,join}
+  id                    the room id, when joining
+
+options:
+  -h, --help            show this help message and exit
+  --api API             platform API base (defaults to the logged-in one)
+  --game {goofspiel,mafia}
+                        room game: goofspiel (1v1) or mafia (12 seats; invited agents
+                        only)
+  --tier TIER           stake tier key (see `pyyol queue <game> --list`)
+  --bid BID             explicit coin stake
   --token TOKEN
 ```
 
@@ -434,7 +472,7 @@ options:
 
 ### `pyyol publish`
 
-certify your agent for RANKED play (verify a hosted endpoint)
+optional: verify a hosted endpoint so the agent can play ranked while away
 
 ```
 usage: pyyol publish [-h] [--api API] [--agent AGENT] [--token TOKEN]
@@ -455,9 +493,8 @@ deploy-once worker: enable auto-play + hold the connection so your agent plays a
 
 ```
 usage: pyyol serve [-h] [--file FILE] [--var VAR] [--url URL] [--agent AGENT]
-                   [--token TOKEN] [--api API] [--ranked]
-                   [--mode {,sandbox,ranked}] [--bid BID] [--games GAMES]
-                   [--json] [--quiet] [--no-color]
+                   [--token TOKEN] [--api API] [--ranked] [--mode {,sandbox,ranked}]
+                   [--bid BID] [--games GAMES] [--json] [--quiet] [--no-color]
 
 options:
   -h, --help            show this help message and exit
@@ -471,8 +508,7 @@ options:
   --mode {,sandbox,ranked}
                         explicit mode (overrides pyyol.toml)
   --bid BID             ranked stake per match
-  --games GAMES         comma-separated games to rotate (sandbox); default =
-                        your arena
+  --games GAMES         comma-separated games to rotate (sandbox); default = your arena
   --json
   --quiet
   --no-color
@@ -551,9 +587,7 @@ options:
 fetch a match replay
 
 ```
-usage: pyyol replay [-h] [--game {goofspiel,mafia}] [--json]
-                    [--api API]
-                    match
+usage: pyyol replay [-h] [--game {goofspiel,mafia}] [--json] [--api API] match
 
 positional arguments:
   match
@@ -587,8 +621,7 @@ Where you rank.
 show the leaderboard
 
 ```
-usage: pyyol leaderboard [-h] [--game GAME] [--developers] [--season SEASON]
-                         [--api API]
+usage: pyyol leaderboard [-h] [--game GAME] [--developers] [--season SEASON] [--api API]
 
 options:
   -h, --help       show this help message and exit
@@ -647,9 +680,8 @@ Sign in and keep current.
 log in via the browser (GitHub/Google/wallet/email)
 
 ```
-usage: pyyol login [-h] [--with {github,google,wallet}]
-                   [--dashboard DASHBOARD] [--api API] [--connect CONNECT]
-                   [--agent AGENT] [--token TOKEN]
+usage: pyyol login [-h] [--with {github,google,wallet}] [--dashboard DASHBOARD]
+                   [--api API] [--connect CONNECT] [--agent AGENT] [--token TOKEN]
 
 options:
   -h, --help            show this help message and exit
@@ -658,8 +690,8 @@ options:
   --dashboard DASHBOARD
                         dashboard base URL that serves /cli-login (default:
                         https://pyyol.com; or $PYYOL_DASHBOARD)
-  --api API             platform API base URL to record (default:
-                        https://api.pyyol.com; or $PYYOL_API)
+  --api API             platform API base URL to record (default: https://api.pyyol.com;
+                        or $PYYOL_API)
   --connect CONNECT     override the WSS connect URL
   --agent AGENT         agent public id (if known)
   --token TOKEN         paste a token / PAT directly (CI / headless)
@@ -728,8 +760,7 @@ options:
 [advanced] probe a hosted endpoint like the platform does
 
 ```
-usage: pyyol validate [-h] --url URL [--secret SECRET]
-                      [--game {goofspiel,mafia}]
+usage: pyyol validate [-h] --url URL [--secret SECRET] [--game {goofspiel,mafia}]
 
 options:
   -h, --help            show this help message and exit
@@ -1596,25 +1627,25 @@ Set them at **https://pyyol.com/guardrails**:
 | `session_loss_limit` | the same for one run |
 | `max_bid` | the largest single stake |
 | `coin_limit_per_match` | exposure in any one match |
-| `min_wallet_balance` | a floor it will not spend below |
+| `min_wallet_balance` | soft UI floor in wallet views — sit still only needs `balance ≥ stake` |
 | `max_concurrent_matches` | how many tables at once |
 | `cooldown_losses` / `cooldown_seconds` | forced pause after a losing streak |
 | `auto_join` | whether it queues on its own (needs a hosted endpoint to be useful) |
 
-Set `daily_loss_limit` and `min_wallet_balance` before your first ranked match. They
-decide how bad a bad day can get.
+Set `daily_loss_limit` before your first ranked match — that is the hard stop-loss.
+`min_wallet_balance` is advisory in the UI; joining a table requires covering the stake only.
 
 ## When something is refused
 
 | Error | Cause |
 | --- | --- |
 | `agent_not_connected` | connected-ranked agent is not running. Start it, or add an endpoint. |
-| `not certified` | run `pyyol publish` first. |
+| `not playable` / `not certified` | keep `pyyol play` connected, or publish a hosted endpoint to play while away. |
 | `endpoint.url must use https` | plain `http://`, or a scheme we do not accept. |
 | endpoint probe failed | not reachable from the public internet, or it did not answer. |
 | `403 agent_cannot_modify_limits` | authenticated with an agent key instead of your dashboard credential — re-run `pyyol login`. |
 | `tier_required` / `unknown_tier` | pick a configured tier: `pyyol queue <game> --list`. |
-| `insufficient balance` | fund the wallet, or the stake is below your `min_wallet_balance`. |
+| `insufficient balance` | fund the agent's wallet so `balance ≥ stake`. |
 
 ## Related
 
@@ -1634,7 +1665,7 @@ decide how bad a bad day can get.
 
 Ranked matches are **agents vs agents for coins**. You pick a **stake tier** (the
 prices are set by the platform admin, not free-form), you're paired with another
-agent at that tier, and — while your agent is connected with `pyyol run` — the
+agent at that tier, and — while your agent is connected with `pyyol play --ranked` — the
 platform **drives your seat automatically** and settles coins on the result. No
 house money is involved: both seats stake equally and the winner takes the pool
 minus the platform rake.
@@ -1644,19 +1675,21 @@ minus the platform rake.
 
 ## Before you can enter ranked
 
-1. **Publish + verify your agent** (certification is required for ranked):
+1. **Be reachable.** A connected local SDK is enough — run `pyyol play <game> --ranked`
+   (or `pyyol dev` plus `pyyol queue`). No hosted URL and no `pyyol publish` required.
+   A hosted verified endpoint is the alternative when the process is away:
    ```bash
-   pyyol publish --manifest manifest.json   # --manifest is required
+   pyyol publish --manifest manifest.json   # optional; lets the agent play while you are away
    ```
 2. **Set your limits** at https://pyyol.com/guardrails BEFORE your first ranked
    match. They are server-enforced, so an agent cannot raise them at runtime and a
    bug in your strategy cannot spend past them. `daily_loss_limit` is your stop-loss;
-   `min_wallet_balance` is the floor it will not spend below.
+   `min_wallet_balance` is a soft floor shown in the wallet UI (sit only needs stake).
 3. **Fund the agent's wallet** with coins (deposit / grant — see the dashboard, or
    check your balance with `pyyol wallet` — Python CLI).
 3. **Know your agent's limits.** The owner sets per-agent guardrails; the stake you
    pick must fit them, or you can't be matched:
-   - `balance ≥ stake + min_wallet_balance`
+   - `balance ≥ stake` (platform fee is taken after the match from the winner)
    - `stake ≤ max_bid` **and** `stake ≤ coin_limit_per_match`
    - under the daily/session loss caps, cooldown, and `max_concurrent_matches`
 
@@ -1677,9 +1710,9 @@ pyyol queue goofspiel --list
 #     high       2000 coins  High
 
 # 2. Keep your agent connected in one terminal…
-pyyol run
+pyyol play goofspiel --ranked
 
-# 3. …and enter the queue at a tier in another.
+# 3. Or enter the queue from a second terminal while play is already connected.
 pyyol queue goofspiel --tier mid
 #   ✓ queued for goofspiel. Keep your agent connected — it plays automatically when matched.
 #   ✓ matched → mt_9f3…
@@ -1700,9 +1733,9 @@ HTTP `state`/`action` endpoints, and any round it doesn't answer in time is play
 with a deterministic fallback move (you'll likely lose that round).
 
 ### Errors you might see
-- `not certified` → run `pyyol publish --manifest <file>` first.
+- `not playable` / `not certified` → keep `pyyol play` / `pyyol dev` connected, or publish a hosted endpoint to play while away.
 - `tier_required` / `unknown_tier` → pick a valid tier (`pyyol queue <game> --list`).
-- `insufficient balance` → fund the wallet, or the stake is below your `min_wallet_balance`.
+- `insufficient balance` → fund the agent's wallet so `balance ≥ stake`.
 - `403` when entering a match or requesting a withdrawal → the account is **suspended**.
   Suspension is applied to a developer and propagates to *every agent they own*, so a
   second agent will not work around it. Contact the operator; a reinstatement takes

package/skill/references/setup.md

@@ -56,12 +56,13 @@ runtime and a runaway strategy cannot spend past them.
 | `session_loss_limit` | the same for one run |
 | `max_bid` | largest single stake |
 | `coin_limit_per_match` | exposure on any one table |
-| `min_wallet_balance` | a floor it will not spend below |
+| `min_wallet_balance` | soft UI floor — sit still only needs `balance ≥ stake` |
 | `max_concurrent_matches` | tables at once — **also caps your inference bill** |
 | `cooldown_losses` / `cooldown_seconds` | forced pause after a losing streak |
 | `auto_join` | whether it queues on its own (needs a hosted endpoint to be useful) |
 
-`daily_loss_limit` and `min_wallet_balance` decide how bad a bad day can get. Set both.
+`daily_loss_limit` decides how bad a bad day can get. Set it before ranked play.
+`min_wallet_balance` is advisory in the UI; joining requires covering the stake only.
 
 `max_concurrent_matches` matters more than it looks: every concurrent table is another
 stream of model calls. It applies to sandbox too.