@mason-data/cli 0.9.0 → 0.11.0

package/dist/src/cli/main.js

@@ -12,28 +12,71 @@
  */
 // FIRST: it sizes libuv's pool, which nothing below may have started (src/cli/pool-size.cjs)
 import "./pool-size.cjs";
-import { COMMANDS, orientation, topUsage, version } from "./registry.js";
+import { COMMANDS, orientation, runVersion, topUsage } from "./registry.js";
 import { didYouMean } from "../lib/did-you-mean.js";
 import { spinUntilOutput } from "./style.js";
 import { CommandFailed, failed, wantsJson } from "./command.js";
 import { RunUnreachable } from "./control.js";
 import { exitWhenWritten } from "../lib/exit-when-written.js";
 import { gatedExit, installOutputGate } from "./output-gate.js";
-async function main(argv) {
+import * as fs from "node:fs";
+/** `-C <folder>` before the command, as git's and make's (each one from the last): the folders, and the line after them. */
+function leadingFolders(argv) {
+    const folders = [];
+    let i = 0;
+    while (argv[i] === "-C") {
+        folders.push(argv[i + 1]);
+        i += 2;
+    }
+    return { folders, rest: argv.slice(i) };
+}
+/** Runs in each `-C` folder in turn, so the command means the project there; a folder missing or unreadable is a wrong
+ *  line, said before anything runs. Null once moved. */
+function moveTo(folders, json) {
+    for (const dir of folders) {
+        const wrong = (message) => failed("", { message, code: "usage", fix: "mason -C <folder> <command>: the command runs as if started in that folder" }, { json });
+        if (dir === undefined || dir === "")
+            return wrong("-C needs a folder: mason -C <folder> <command>");
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch (e) {
+            return wrong(`-C ${JSON.stringify(dir)}: ${e.code === "ENOENT" ? "there is no such folder" : "it cannot be read"}`);
+        }
+        if (!st.isDirectory())
+            return wrong(`-C ${JSON.stringify(dir)}: it is not a folder`);
+        try {
+            fs.accessSync(dir, fs.constants.R_OK | fs.constants.X_OK);
+            process.chdir(dir);
+        }
+        catch {
+            return wrong(`-C ${JSON.stringify(dir)}: it cannot be read`);
+        }
+    }
+    return null;
+}
+async function main(line) {
+    // -C <folder> first: everything after it, the project lookup included, is as if started there
+    const { folders, rest: argv } = leadingFolders(line);
     const [command, ...args] = argv;
+    const moved = moveTo(folders, wantsJson(args, COMMANDS.find((c) => c.name === command)));
+    if (moved !== null)
+        return moved;
     // mason alone: where you are and the next command; mason help / --help: every command
     if (command === undefined) {
         process.stdout.write(await orientation(process.cwd()));
         return 0;
     }
+    // mason --help --json is mason help --json: every command's spec as data
     if (command === "--help" || command === "-h") {
+        if (args.includes("--json"))
+            return COMMANDS.find((c) => c.name === "help").run(["--json"]);
         process.stdout.write(topUsage());
         return 0;
     }
-    if (command === "--version" || command === "-v" || command === "version") {
-        process.stdout.write(`${version()}\n`);
-        return 0;
-    }
+    if (command === "--version" || command === "-v" || command === "version")
+        return runVersion(args);
     const cmd = COMMANDS.find((c) => c.name === command);
     const json = wantsJson(args, cmd);
     // the commands' old names: said, never run as different ones
@@ -52,7 +95,7 @@ async function main(argv) {
         list: { message: "mason list is gone: a project is its folder, and a command means the project of the folder it runs in", next: [["mason status", "this folder's project"]] },
     };
     if (!cmd && Object.hasOwn(RENAMED, command))
-        return failed("", { ...RENAMED[command], code: "usage" }, { json });
+        return failed("", { ...RENAMED[command], code: "usage", fix: "run the command that does it now: the next steps name it" }, { json });
     if (!cmd)
         return failed("", { message: `there is no command ${JSON.stringify(command)}${didYouMean(command, COMMANDS.map((c) => c.name))}`, code: "usage", usage: json ? undefined : topUsage() }, { json });
     // a command quiet for a moment shows a spinner on a terminal until it prints (src/cli/style.ts spinUntilOutput)
@@ -81,7 +124,7 @@ main(process.argv.slice(2)).then((code) => exitWhenWritten(gatedExit(code)), (e)
     // stack to be understood is a bug — mason query orders printed one when Mason's API was not up yet).
     // MASON_DEBUG=1 prints where it happened, for the bug report it deserves. The same shape as every failure, JSON under --json.
     const message = e instanceof Error ? e.message : String(e);
-    const [command, ...args] = process.argv.slice(2);
+    const [command, ...args] = leadingFolders(process.argv.slice(2)).rest;
     const code = failed(command ?? "", { message, code: "failed", fix: process.env.MASON_DEBUG ? undefined : "this is a bug in mason: MASON_DEBUG=1 prints where it happened, for the report" }, { json: wantsJson(args, COMMANDS.find((c) => c.name === command)) });
     if (process.env.MASON_DEBUG)
         process.stderr.write(`${e.stack ?? ""}\n`);

package/dist/src/cli/mcp.js

@@ -43,26 +43,24 @@ export const MCP = {
   the request log under application_name mason-mcp/<the client's name>. It serves until the client closes stdin.
   Its stdout is the protocol's: it takes no --json, and a failure to start is said on stderr.
 
-  Its tools: tables; describe (a table); query (one statement; max_rows default 200, at most 10000; timeout_ms
-  default 30000, at most 300000); explain (a statement). Its resources: mason://help/agent and mason://help/mcp.
-
   Claude Code (in the project's folder, with Mason running), the URL in the server's environment:
     mason user add claude                          the URL to paste, printed once
     claude mcp add mason --env MASON_URL="${EXAMPLE_URL}" -- mason mcp
-  or on its command line, where ps shows it to this machine's users and claude mcp add prints it:
-    claude mcp add mason -- mason mcp --url "${EXAMPLE_URL}"
-
-  Claude Desktop (claude_desktop_config.json). The app often starts servers without your shell's PATH, where neither
-  mason nor the node its first line asks for is found: name both by their absolute paths (which node, which mason):
-    { "mcpServers": { "mason": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/mason", "mcp"],
-        "env": { "MASON_URL": "${EXAMPLE_URL}" } } } }
 
   What the client runs:
     MASON_URL="${EXAMPLE_URL}" mason mcp
-    mason mcp --url "${EXAMPLE_URL}"
 
   --url <url>   the Postgres API as a mason user: what mason user add printed (default MASON_URL); TLS as its sslmode
-                says (a host off this machine: require when it names none)
+                says (a host off this machine: require when it names none). A URL with a password here is taken,
+                with a warning on stderr: ps shows it to this machine's users, so MASON_URL is the safer place
+
+  Its tools: tables; describe (a table); query (one statement; max_rows default 200, at most 10000; timeout_ms
+  default 30000, at most 300000); explain (a statement). Its resources: mason://help/agent and mason://help/mcp.
+
+  Claude Desktop (claude_desktop_config.json). The app often starts servers without your shell's PATH, where neither
+  mason nor the node its first line asks for is found: name both by their absolute paths (which node, which mason):
+    { "mcpServers": { "mason": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/mason", "mcp"],
+        "env": { "MASON_URL": "${EXAMPLE_URL}" } } } }
 `,
     options: { url: { type: "string" } },
     stdout: "protocol",
@@ -71,6 +69,8 @@ export const MCP = {
  *  its own log (Claude Code: claude --debug; Claude Desktop: mcp-server-mason.log). A failure to START is failed()'s. */
 const log = (m) => { process.stderr.write(`[mason mcp] ${m}\n`); };
 const NEED_URL = "mason mcp needs a mason user's URL: MASON_URL, or --url";
+/** What `--url` with a password is told on stderr: the safer form, never the password. */
+export const MCP_ARGV_PASSWORD_WARNING = "warning: --url holds the user's password, which ps shows to this machine's users: put the URL in the server's environment as MASON_URL instead (claude mcp add mason --env MASON_URL=… -- mason mcp)";
 const HELP_STEP = ["mason help mcp", "how to add mason mcp to Claude Code or Claude Desktop"];
 const ADD_STEP = ["mason user add claude", "a user for the agent: its password and URL, printed once"];
 /** Where `mason mcp` connects: the URL given, or why there is none (the project's state says what to run). */
@@ -156,6 +156,9 @@ export async function mcp(argv) {
     const source = theSource(u.url, u.from);
     if ("message" in source)
         return failed("mcp", source, { json });
+    // a password on the command line is taken (a client's config may hold it so), and said with the safer form; never repeated
+    if (u.from === "--url" && source.password !== "")
+        log(MCP_ARGV_PASSWORD_WARNING);
     // the URL is checked once, before the protocol starts: a client that cannot connect is told now, in the failure shape
     try {
         (await connect(source, "mason-mcp")).close();

package/dist/src/cli/project.js

@@ -21,6 +21,9 @@ import { randomBytes } from "node:crypto";
 import { connectDatabase, databaseSettingRefusal } from "../lib/database-name.js";
 import { changesRetired, pollMsRetired } from "../lib/table-sync.js";
 import { readSource, sourcesTop, writtenDatabase } from "./sources.js";
+import { UI_SOCKET_SETTING } from "./ui-socket.js";
+import { UI_RUN_FILE_SETTING } from "./ui-run-file.js";
+import { UI_READ_ONLY_SETTING, uiReadOnlySetting } from "./ui-read-only.js";
 export const STATE_DIR = ".mason";
 const CONFIG = "config.json";
 /** A project's name: what its commands call it and (with the source's) what its replication slot is named for. Never
@@ -162,7 +165,7 @@ export function theProject(cwd) {
     if (p)
         return { project: p };
     return { problem: "no Mason project here or above", code: "no_project", fix: "cd into a project's folder, or make this folder one (mason init demo: a demo database, nothing to install)",
-        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"]] };
+        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or its URL on stdin: mason init -)"]] };
 }
 /** Whether `root`'s .gitignore already ignores `.mason/`. */
 export function ignoresStateDir(gitignore) {
@@ -263,5 +266,25 @@ export function startSettingRefusal(p, env, o) {
     if (changes !== null)
         return { code: "refused", ...changes };
     const database = o.serve ? null : databaseSettingRefusal(env, top().shown);
-    return database === null ? null : { code: "refused", ...database };
+    if (database !== null)
+        return { code: "refused", ...database };
+    // a read-only page is a server's (src/cli/ui-read-only.ts): a value not 0 or 1 refuses either start, and 1 mason start's
+    const pageReadOnly = uiReadOnlySetting(env);
+    if (typeof pageReadOnly !== "boolean")
+        return { message: pageReadOnly.problem, code: "refused", fix: `set ${UI_READ_ONLY_SETTING}=1 or ${UI_READ_ONLY_SETTING}=0, or unset it` };
+    if (!o.serve && pageReadOnly) {
+        return { message: `${UI_READ_ONLY_SETTING} is mason serve's setting, and mason start ignores no setting silently`, code: "refused",
+            fix: `unset ${UI_READ_ONLY_SETTING}: mason start's page is yours alone, on this machine` };
+    }
+    // the page's Unix socket is a server's (src/cli/ui-socket.ts): a laptop's page is opened with mason ui
+    if (!o.serve && env[UI_SOCKET_SETTING]) {
+        return { message: `${UI_SOCKET_SETTING} is mason serve's setting, and mason start ignores no setting silently`, code: "refused",
+            fix: `unset ${UI_SOCKET_SETTING}: mason ui opens this run's page` };
+    }
+    // the run's file is a server's supervisor's (src/cli/ui-run-file.ts): a laptop's commands read the project's config
+    if (!o.serve && env[UI_RUN_FILE_SETTING]) {
+        return { message: `${UI_RUN_FILE_SETTING} is mason serve's setting, and mason start ignores no setting silently`, code: "refused",
+            fix: `unset ${UI_RUN_FILE_SETTING}: mason ui opens this run's page, and the mason commands reach the run by themselves` };
+    }
+    return null;
 }

package/dist/src/cli/registry.js

@@ -3,7 +3,7 @@
  * command's summary, in this order — so a command cannot exist without being listed, and tests/cli-help.test.ts holds
  * each one to src/cli/command.ts's rules (its own --help, an example, every option documented).
  */
-import { failed, parseCommand, reportText, wantsJson } from "./command.js";
+import { FAILURE_CODES, SPEC_NEXT, failed, jsonText, parseCommand, reportText, specAnswer, specJson, wantsJson } from "./command.js";
 import { removedStartFlags } from "../lib/table-sync.js";
 import { sourcesTop } from "./sources.js";
 import { dev } from "./dev.js";
@@ -37,7 +37,7 @@ export const DEV = {
     needs: "project",
     name: "start",
     summary: "start Mason for this folder's project, in the background (mason init makes the project)",
-    usage: `usage: mason start [--attach] [--self-signed-tls] [--port <n>] [--json]
+    usage: `usage: mason start [--attach] [--self-signed-tls] [--ui-port <n>] [--json]
 
   Starts Mason for the project of this folder (mason init made it): one process, which syncs the tables you add
   (mason add) from the project's database into its own file, keeps them current as the sources file says, and answers
@@ -45,6 +45,17 @@ export const DEV = {
   its sync: says replication). It returns once Mason is up; run it again any time (it says so when Mason is
   already running). The synced data and Mason's state stay between runs: the next start resumes.
 
+    mason start
+    mason start --attach      in the foreground: Ctrl-C stops it
+    MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
+
+  --attach            stay in the foreground (Ctrl-C stops Mason)
+  --self-signed-tls   the Postgres API requires TLS, from a certificate made for this project in .mason/ (kept and
+                      served again by every later start with the flag); not with MASON_PG_TLS_CERT / _KEY
+  --ui-port <n>       the port of its web page and of the mason commands, on 127.0.0.1 (default ${DEFAULT_UI_PORT}, or the
+                      next free one); MASON_UI_PORT on a server, never the Postgres API's (MASON_PG_PORT)
+  --json              as data, once it is up: { running, pid, postgres: { url, host, port, database, sslmode }, next }
+
   After its first sync, each table is kept current as the sources file's sync: says — at the top for every table, or
   on a table's entry: off (the default, which mason init writes) reads it again only when you run mason sync <table>;
   poll <interval> (poll 5s, poll 5m, poll 1h) polls it with SELECTs at that interval; replication reads its changes
@@ -61,7 +72,8 @@ export const DEV = {
   created, altered or dropped — Mason makes only its slot. A read replica needs one (it takes no CREATE PUBLICATION).
 
   --replication, --poll and --publication are gone: each answers with the line to write at the top of the sources
-  file (sync: replication, sync: poll 5m, publication: <name>) and exit 2, and starts nothing.
+  file (sync: replication, sync: poll 5m, publication: <name>) and exit 2, and starts nothing. --port is now
+  --ui-port: it answers with the line to run and exit 2.
 
   The Postgres API's port is the project's: the first start takes 5433, or the next port free on every address when a
   second Postgres holds it, and records it; every later start listens on the same port, so a BI tool's saved connection
@@ -78,42 +90,36 @@ export const DEV = {
   any other address is refused.
 
   ${PROJECT_LINE}
-
-    mason start
-    mason start --attach      in the foreground: Ctrl-C stops it
-    MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
-
-  --attach            stay in the foreground (Ctrl-C stops Mason)
-  --self-signed-tls   the Postgres API requires TLS, from a certificate made for this project in .mason/ (kept and
-                      served again by every later start with the flag); not with MASON_PG_TLS_CERT / _KEY
-  --port <n>          the port the mason commands reach it on (default ${DEFAULT_UI_PORT}, or the next free one)
-  --json              as data, once it is up: { running, pid, postgres: { url, host, port, database, sslmode }, next }
 `,
     options: {
-        port: { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
+        "ui-port": { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
         "self-signed-tls": { type: "boolean", default: false },
     },
     json: ["running", "pid", "postgres", "next"],
 };
 async function runDev(argv) {
-    // --replication, --poll and --publication are gone (issue 33): each answered with the edit to make in the sources
+    // --replication, --poll and --publication are gone (issue 33), and --port is --ui-port: each answered with the edit to make in the sources
     // file, exit 2, before the options are parsed (it would be an unknown option there) and before anything starts. The
     // file is read only when one is given. A decision: `mason start --replication --help` answers the refusal, not the
     // usage — the flag is wrong whatever else the line asks
     const removed = removedStartFlags(argv, () => startSourcesTop(process.cwd()));
-    if (removed !== null)
-        return failed("start", { code: "usage", ...removed, next: [["mason start", "each table kept current as its sync: says"], ["mason help production", "sync: and publication:, and what each needs"]] }, { json: wantsJson(argv, DEV) });
+    if (removed !== null) {
+        const { start, sync, ...said } = removed;
+        const next = sync ? [[start, "each table kept current as its sync: says"], ["mason help production", "sync: and publication:, and what each needs"]]
+            : [[start, "Mason, its web page and the commands on that port"]];
+        return failed("start", { code: "usage", ...said, next }, { json: wantsJson(argv, DEV) });
+    }
     const f = parseCommand(DEV, argv);
     if (typeof f === "number")
         return f;
     const v = f.values;
     if (f.positionals.length) {
         // the database is the project's now: a URL here is the old habit, answered with the new way
-        return failed("start", { message: "it takes no database URL: the project has one", code: "usage", why: "mason init <url> made it; .mason/config.json holds it", usage: DEV.usage }, { json: v.json });
+        return failed("start", { message: "it takes no database URL: the project has one", code: "usage", why: "mason init <url> made it; .mason/config.json holds it", fix: "run mason start alone", usage: DEV.usage }, { json: v.json });
     }
-    const port = v.port === undefined ? DEFAULT_UI_PORT : Number(v.port);
+    const port = v["ui-port"] === undefined ? DEFAULT_UI_PORT : Number(v["ui-port"]);
     if (!Number.isInteger(port) || port < 1 || port > 65_535)
-        return failed("start", { message: `--port must be a port number (1-65535), not ${JSON.stringify(v.port)}`, code: "usage" }, { json: v.json });
+        return failed("start", { message: `--ui-port must be a port number (1-65535), not ${JSON.stringify(v["ui-port"])}`, code: "usage" }, { json: v.json });
     if (!v.attach)
         return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
     return dev({ port, version: version(), selfSignedTls: v["self-signed-tls"] });
@@ -127,7 +133,7 @@ function startSourcesTop(cwd) {
 export const HELP = {
     name: "help",
     summary: "the commands by step, or one command's usage: mason help add",
-    usage: `usage: mason help [<command> | <guide>]
+    usage: `usage: mason help [<command> | <guide>] [--json]
 
   The commands by step (mason help), how to use one (mason help add — the same as mason add --help), or a guide,
   offline, short enough to read whole and listing exactly what Mason accepts:
@@ -135,35 +141,74 @@ export const HELP = {
     mason help
     mason help add
 ${Object.entries(GUIDES).map(([k, v]) => `    mason help ${k.padEnd(14)} ${v}`).join("\n")}
+    mason help --json         every command's spec as data (mason help agent says its shape)
+
+  --json   as data: mason help, { version, commands: [<spec>…], guides: [{ name, summary }], failureCodes:
+           [{ code, meaning }], next }; mason help <command> (the same as mason <command> --help --json), { command:
+           <spec>, next }; mason help <guide>, { guide: { name, summary, text }, next }
 `,
-    options: {},
+    options: { json: { type: "boolean", default: false } },
+    json: ["version", "commands", "guides", "failureCodes", "command", "guide", "next"],
 };
+/** `mason version` (also `--version`, `-v`): the CLI's version, as text or with --json as data. Answered by main.ts
+ *  before the registry, so not one of COMMANDS; described here so `mason help version` and its --json read one spec. */
+export const VERSION = {
+    name: "version",
+    summary: "the CLI's version",
+    usage: `usage: mason version [--json]
+
+  The CLI's version (mason --version and mason -v are the same):
+
+    mason version
+
+  --json   as data: { version, next }
+`,
+    options: { json: { type: "boolean", default: false } },
+    json: ["version", "next"],
+};
+/** `mason version` (and `--version`, `-v`): its line read by VERSION, as every command's is by its spec, so what it
+ *  accepts is what its spec as data says — `--help`, `--help --json`, a wrong option or an argument refused (exit 2). */
+export function runVersion(argv) {
+    const f = parseCommand(VERSION, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    if (f.positionals.length)
+        return failed("version", { message: `it takes no argument: ${f.positionals.join(" ")}`, code: "usage", usage: VERSION.usage }, { json });
+    process.stdout.write(`${json ? jsonText(VERSION, { version: version() }) : version()}\n`);
+    return 0;
+}
 async function runHelp(argv) {
     const f = parseCommand(HELP, argv);
     if (typeof f === "number")
         return f;
+    const json = f.values.json === true;
     const [asked, ...rest] = f.positionals;
     if (rest.length)
-        return failed("help", { message: "one command or guide at a time", code: "usage", usage: HELP.usage }, { json: false });
+        return failed("help", { message: "one command or guide at a time", code: "usage", usage: HELP.usage }, { json });
     if (asked === undefined) {
-        process.stdout.write(topUsage());
-        return 0;
-    }
-    if (asked === "version") {
-        process.stdout.write("usage: mason version (or --version, -v): the CLI's version\n");
+        if (!json) {
+            process.stdout.write(topUsage());
+            return 0;
+        }
+        process.stdout.write(`${jsonText(HELP, {
+            version: version(), commands: [...COMMANDS, VERSION].map(specJson), guides: Object.entries(GUIDES).map(([name, summary]) => ({ name, summary })),
+            failureCodes: Object.entries(FAILURE_CODES).map(([code, meaning]) => ({ code, meaning })),
+        }, [["mason help agent", "driving Mason from a coding agent: these shapes, the failures and the exit codes"]])}\n`);
         return 0;
     }
     if (Object.hasOwn(GUIDES, asked)) {
-        process.stdout.write(await guideText(asked));
+        const text = await guideText(asked);
+        process.stdout.write(json ? `${jsonText(HELP, { guide: { name: asked, summary: GUIDES[asked], text } }, SPEC_NEXT)}\n` : text);
         return 0;
     }
-    const cmd = COMMANDS.find((c) => c.name === asked);
+    const cmd = asked === "version" ? VERSION : COMMANDS.find((c) => c.name === asked);
     if (cmd) {
-        process.stdout.write(cmd.usage);
+        process.stdout.write(json ? `${specAnswer(cmd)}\n` : cmd.usage);
         return 0;
     }
     return failed("help", { message: `there is no command or guide ${JSON.stringify(asked)}${didYouMean(asked, [...COMMANDS.map((c) => c.name), ...Object.keys(GUIDES)])}`, code: "usage",
-        why: `the guides: ${Object.keys(GUIDES).join(", ")}`, next: [["mason help", "every command"]] }, { json: false });
+        why: `the guides: ${Object.keys(GUIDES).join(", ")}`, fix: "name a command or a guide mason help lists", next: [["mason help", "every command"]] }, { json });
 }
 /**
  * EVERY COMMAND, IN THE ORDER A FIRST SESSION NEEDS THEM (listed in the order a developer will likely need them, the
@@ -198,7 +243,7 @@ export async function orientation(cwd, s = styleOut()) {
         ? [["Project", `${project.config.name}, files in ${project.folder}`], ["Mason", run ? `running (pid ${run.pid})` : "not running"]]
         : [["Project", "none here: mason init makes this folder one"]];
     const next = !project
-        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"],
+        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or its URL on stdin: mason init -)"],
             ["mason init demo", "or try it on a demo database Mason makes itself: nothing to install"],
             ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
         : !run ? [["mason start", "start Mason for this project, in the background"], ["mason status", "the project and its tables"]]
@@ -238,10 +283,10 @@ export function topUsage(s = styleOut()) {
         listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),
         "",
         para("mason <command> --help (or mason help <command>) says how to use one, with examples; the guides are offline and short enough to read whole."),
-        para("A command means the project of the folder it runs in (or above it)."),
+        para("A command means the project of the folder it runs in (or above it); mason -C <folder> <command> runs it as if started in that folder."),
         para("Every command but help and mcp (whose stdout is the MCP protocol's) takes --json: one JSON object for a program, always with next (what to run " +
             "next); a failure is { error: { code, message, why, fix }, next }. The exit code says how it went: 0 done, 1 failed " +
-            "with the reason, 2 a wrong command line, 124 a wait timed out (mason wait, mason deploy, mason replica create). Driving Mason from a coding agent: mason help agent."),
+            "with the reason, 2 a wrong command line, 124 a wait timed out (mason wait, mason deploy, mason replica create, mason replica delete). Driving Mason from a coding agent: mason help agent."),
         "",
     ].join("\n");
 }