@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/args.d.ts

@@ -0,0 +1,160 @@
+export interface ParsedArgs {
+    command: string | null;
+    /** Positional arguments after the command. */
+    operands: string[];
+    server?: string;
+    network?: string;
+    help: boolean;
+    version: boolean;
+    /** Machine-readable output where a command has one. */
+    json: boolean;
+    /** Include what is in the trash. */
+    all: boolean;
+    /** Where to write a fetched file. */
+    out?: string;
+    /** Replace a file that is already there. */
+    force: boolean;
+    /** The name an uploaded file gets in the drive. */
+    name?: string;
+    /** The destination folder for an upload. */
+    to?: string;
+    /** Say what an upload would cost and stop. */
+    dryRun: boolean;
+    /** `put`: how much of a file goes into one part. A byte count, optionally with a unit. */
+    partSize?: string;
+    /** `put`/`push`: what THIS run does about a name already in use. Absent = this machine's setting. */
+    onCollision?: string;
+    /** `put`/`push`: credits THIS upload sets aside per file, 0 to 64. Absent = the account's default. */
+    deposit?: string;
+    /** Answer yes to a warning this run would otherwise stop on. */
+    yes: boolean;
+    /** `public-code`: publish this account's public code on the server. Permanent. */
+    publish: boolean;
+    /** `login`: store the NMTS key unsealed rather than under a passphrase. */
+    plain: boolean;
+    /** `login`: store nothing; print the environment variable to set. */
+    env: boolean;
+    /** `verify`: report whether the human check is live and stop, asking for no new code. */
+    status: boolean;
+    /** `create`: print the registration address and stop, rather than waiting for a person. */
+    noWait?: boolean;
+    /** `ls`: keep only files whose name contains this text, case-insensitively. */
+    find?: string;
+    /** `ls`: which order to list in — `name`, `size` or `date`. Absent = the path order. */
+    sort?: string;
+    /** `ls`: reverse whichever order is in effect. */
+    desc: boolean;
+    /** `push`: include entries whose name begins with a dot. */
+    hidden: boolean;
+    /** `extend`: how many of the storage network's epochs to add; `put`/`push --pay wallet`: how many to buy. */
+    epochs?: string;
+    /** `put`/`push`: who pays for the storage — `credits` (the default) or `wallet`. */
+    pay?: string;
+    /** `put --pay wallet`: `fit`, `whole`, or a held storage resource's object id. */
+    storage?: string;
+    /** `consent grant wallet`: how long the grant lasts (days, at most 30), or until a date.
+     *  `key new`: how many days the new API key lasts. The server clamps at its own ceiling. */
+    days?: string;
+    until?: string;
+    /** `consent grant wallet`: `storage` or `all`. */
+    scope?: string;
+    /** `key new`: which permissions the key carries — `read`, `write`, `spend`, comma-separated. */
+    scopes?: string;
+    /** `consent grant wallet`: ceilings in coins. */
+    capWal?: string;
+    capSui?: string;
+    /** `wallet send` · `wallet swap`: a ceiling on the chain fee, in SUI. */
+    feeCap?: string;
+    /** `wallet swap`: which venue, deepbook or bluefin. Without it both are quoted and the run stops. */
+    venue?: string;
+    /** `wallet swap`: the slippage allowance in whole bps (1 bps = 0.01%). */
+    slippageBps?: string;
+    /** `wallet swap`: a person's say past the extremes gate. Refused while a mode is on. */
+    acceptExtremes: boolean;
+    /** `s3`: which loopback port the gateway listens on. */
+    port?: string;
+    /**
+     * `create`: the version of the Terms of Service a PERSON read and accepts for the new account.
+     *
+     * ⛔ IT IS A VALUE AND NOT A FLAG, so that what was accepted is on the command line rather than
+     *    implied by it. A tool that could accept "whatever is current" would be agreeing on behalf
+     *    of somebody who never saw a version number.
+     */
+    acceptTerms?: string;
+    /** `create`: the version of the Privacy Policy accepted in the same act. */
+    acceptPrivacy?: string;
+    /** `losses`: ask the chain about ONE listed storage object now, instead of listing. */
+    recheck?: string;
+    /** `losses`: take ONE line off this account's own drive, instead of listing. ⛔ A VALUE AND NOT
+     *  A FLAG, so the line put down is named on the command line: a person reads one and puts it down. */
+    dismiss?: string;
+    /** `shares`: who ONE file was shared with, instead of what was shared with this account. */
+    sent?: string;
+    /** ultra-high acts under skip-permissions: why this is right to do now. Kept in the run log. */
+    reason?: string;
+    releaseStorage: boolean;
+    size?: string;
+    /** `devices`: sign ONE device out by id, or `all` — a person's act, proved by the NMTS key. */
+    signOut?: string;
+    /**
+     * `label`: the label to rename. The NEW name follows as the operand.
+     *
+     * ⛔ ONE VALUE, NOT TWO, because the table above gives every option exactly one — and a second
+     *    spelling of "how many values does this take" is how an option ends up parsed one way and
+     *    tested another. What a person types is still `label --rename <old> <new>`: the new name is
+     *    read from the operands, which is where `label <name> <files>` already reads a name from.
+     */
+    rename?: string;
+    /** `support send`: what the report is about, and optionally which part of that. */
+    category?: string;
+    sub?: string;
+    /** `support`: the message itself, or the file holding it. */
+    message?: string;
+    messageFile?: string;
+    /**
+     * `support send`: attach the run log, and how many runs of it.
+     * ⛔ THE EMPTY STRING IS "GIVEN WITH NO NUMBER", which is different from absent. A boolean
+     *    beside a count would be two fields answering one question, and the pair can disagree.
+     */
+    attachLog?: string;
+    /**
+     * `support`: values that must not travel, replaced wherever they appear.
+     *
+     * ⛔ THE ONLY REPEATABLE OPTION, and it is repeatable because what it names is one value at a
+     *    time. A comma-separated list would make a comma impossible to omit.
+     */
+    omit?: string[];
+    /**
+     * `whoami`: print the NMTS key itself.
+     *
+     * ⛔ A FLAG AND NOT A VALUE — it names no secret, it asks for the one this machine already
+     *    holds. The option table is checked for names that look like credentials; this one carries
+     *    nothing and says what it does.
+     */
+    reveal: boolean;
+    /**
+     * `key new`: put the new key on the screen once, as well as storing it. A flag and not a value
+     * for the reason above: it names no secret, it asks for the one this run was just handed.
+     */
+    print: boolean;
+    /** `nmts wallet address --qr` — the address as a QR code in the terminal as well. */
+    qr: boolean;
+    /** `wallet hall --remove`: be listed by a shortened address again. Never with `--name`. */
+    remove: boolean;
+    /** `terms`/`privacy`: which language to fetch — `en` or `ko`. Absent = English. */
+    lang?: string;
+    /** `terms`: the message board's terms rather than the service's. */
+    board: boolean;
+    /**
+     * `notices`/`terms`/`privacy`: keep the document as a file instead of printing it.
+     *
+     * ⛔ A FLAG, AND THE NOTICE'S ID IS STILL THE OPERAND. `notices --save <id>` reads exactly like
+     *    `notices <id>`, which is the point: one way to name a notice, whichever of the two things
+     *    is being done with it. The file's NAME is never an option — it is the server's, so that a
+     *    copy kept here and a copy kept from the browser are the same file.
+     */
+    save: boolean;
+}
+export declare const OPTIONS_TAKING_A_VALUE: string[];
+export declare const FLAGS: string[];
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/args.js

@@ -1,16 +1,12 @@
 // Turning argv into a command and its options.
 //
-// ⛔ NO SECRET IS EVER AN OPTION. There is no --code and no --api-key, and adding one would undo
-//    the reason the credentials module exists: on Linux any process can read another's command
-//    line, and the shell records it. A test asserts that no option name here looks like a secret.
+// ⛔ NO SECRET IS EVER AN OPTION. There is no --code and no --api-key: on Linux any process can read
+//    another's command line, and the shell records it. A test asserts no option name looks like one.
 //
-// ⛔ AN UNKNOWN OPTION IS AN ERROR, NOT A SHRUG. Ignoring it means `--serverr https://…` silently
-//    talks to the live server, and an agent retrying with a typo would never learn why.
+// ⛔ AN UNKNOWN OPTION IS AN ERROR, NOT A SHRUG: `--serverr` must not silently talk to the live server.
 //
-// ⛔ THE OPTIONS ARE A TABLE, NOT A LADDER OF `if`s. Every option used to be written three times —
-//    once in the list a test reads, once as `--x value` and once as `--x=value` — and adding one
-//    meant remembering all three. Now the table below is the only place, so an option cannot exist
-//    in one spelling and not the other.
+// ⛔ THE OPTIONS ARE A TABLE, NOT A LADDER OF `if`s: the tables below are the only place an option
+//    is spelled, so it cannot exist as `--x value` and not as `--x=value`.
 import { NmtsError } from "./errors.js";
 /** Which field a value-taking option fills. */
 const VALUE_OPTIONS = {
@@ -21,12 +17,56 @@ const VALUE_OPTIONS = {
     "--to": "to",
     "--part-size": "partSize",
     "--on-collision": "onCollision",
+    "--deposit": "deposit",
     "--find": "find",
     "--sort": "sort",
     "--epochs": "epochs",
+    "--pay": "pay",
+    "--storage": "storage",
+    "--days": "days",
+    "--until": "until",
+    "--scope": "scope",
+    "--scopes": "scopes",
+    "--cap-wal": "capWal",
+    "--cap-sui": "capSui",
+    "--fee-cap": "feeCap",
+    "--venue": "venue",
+    "--slippage-bps": "slippageBps",
     "--port": "port",
     "--accept-terms": "acceptTerms",
     "--accept-privacy": "acceptPrivacy",
+    "--recheck": "recheck",
+    "--dismiss": "dismiss",
+    "--sent": "sent",
+    "--reason": "reason",
+    "--size": "size",
+    "--sign-out": "signOut",
+    "--rename": "rename",
+    "--category": "category",
+    "--sub": "sub",
+    "--message": "message",
+    "--message-file": "messageFile",
+    "--lang": "lang",
+};
+/**
+ * Which field an option that may be given more than once appends to.
+ *
+ * ⛔ ITS OWN TABLE, so that "repeatable" is a property of the option rather than of the code that
+ *    happens to read it. An option in the value table that a caller repeats today keeps only the
+ *    last one, silently, which is the wrong answer for a list of values to remove.
+ */
+const LIST_OPTIONS = {
+    "--omit": "omit",
+};
+/**
+ * Which field an option that MAY carry a value fills, with "" for a bare one.
+ *
+ * ⛔ THE VALUE IS TAKEN ONLY WHEN IT IS A NUMBER. `--attach-log send` must not read `send` as a
+ *    count and leave the command line without its action; every value this shape of option takes
+ *    is a count, so "is it digits" is the whole question.
+ */
+const OPTIONAL_VALUE_OPTIONS = {
+    "--attach-log": "attachLog",
 };
 /** Which field a flag sets to true. */
 const FLAG_OPTIONS = {
@@ -44,39 +84,59 @@ const FLAG_OPTIONS = {
     "--plain": "plain",
     "--env": "env",
     "--status": "status",
-    "--i-accept-the-risk": "iAcceptTheRisk",
+    "--no-wait": "noWait",
     "--desc": "desc",
     "--hidden": "hidden",
+    "--reveal": "reveal",
+    "--release-storage": "releaseStorage",
+    "--print": "print",
+    "--qr": "qr",
+    "--board": "board",
+    "--save": "save",
+    "--remove": "remove",
+    "--accept-extremes": "acceptExtremes",
 };
 // ⛔ Derived from the tables, not written again. A hand-kept list is how an option ends up tested
-//    for one property and accepted with another.
-export const OPTIONS_TAKING_A_VALUE = Object.keys(VALUE_OPTIONS);
+//    for one property and accepted with another. ⚠ Every option that carries a value is in here,
+//    whichever table it lives in — the test that refuses a secret-looking option name reads this.
+export const OPTIONS_TAKING_A_VALUE = [
+    ...Object.keys(VALUE_OPTIONS),
+    ...Object.keys(LIST_OPTIONS),
+    ...Object.keys(OPTIONAL_VALUE_OPTIONS),
+];
 export const FLAGS = Object.keys(FLAG_OPTIONS);
 function isValueOption(token) {
     return Object.hasOwn(VALUE_OPTIONS, token);
 }
+function isListOption(token) {
+    return Object.hasOwn(LIST_OPTIONS, token);
+}
+function isOptionalValueOption(token) {
+    return Object.hasOwn(OPTIONAL_VALUE_OPTIONS, token);
+}
 function isFlag(token) {
     return Object.hasOwn(FLAG_OPTIONS, token);
 }
+/** A whole number and nothing else. What an optional value is allowed to be. */
+const DIGITS = /^[0-9]+$/u;
+/** Add one more value to a repeatable option's field. */
+function append(parsed, field, value) {
+    const held = parsed[field];
+    parsed[field] = held === undefined ? [value] : [...held, value];
+}
+/**
+ * Every flag starts false. ⛔ THE KEY TYPE IS DERIVED FROM THE TABLE, so a flag added above and
+ * forgotten here stops the build — and written out one flag at a time rather than built at run
+ * time, because a shape the compiler cannot see would let a new flag arrive as `undefined`.
+ */
+const FLAG_DEFAULTS = {
+    help: false, version: false, json: false, all: false, force: false, dryRun: false, releaseStorage: false,
+    yes: false, publish: false, plain: false, env: false, status: false,
+    desc: false, hidden: false, reveal: false, print: false, qr: false, board: false,
+    save: false, acceptExtremes: false, remove: false, noWait: false,
+};
 export function parseArgs(argv) {
-    const parsed = {
-        command: null,
-        operands: [],
-        help: false,
-        version: false,
-        json: false,
-        all: false,
-        force: false,
-        publish: false,
-        dryRun: false,
-        yes: false,
-        plain: false,
-        env: false,
-        status: false,
-        iAcceptTheRisk: false,
-        desc: false,
-        hidden: false,
-    };
+    const parsed = { command: null, operands: [], ...FLAG_DEFAULTS };
     let index = 0;
     // ⛔ EVERYTHING AFTER `--` IS A NAME, NOT AN OPTION. Files in a drive are named by people and by
     //    other programs, and a name is allowed to start with a dash. Without this, `nmts rm -h`
@@ -100,6 +160,26 @@ export function parseArgs(argv) {
             parsed[FLAG_OPTIONS[token]] = true;
             continue;
         }
+        if (isListOption(token)) {
+            const value = argv[index];
+            if (value === undefined || (value.startsWith("-") && value !== "-")) {
+                throw new NmtsError(`${token} needs a value after it.`, { exitCode: 2 });
+            }
+            index += 1;
+            append(parsed, LIST_OPTIONS[token], value);
+            continue;
+        }
+        if (isOptionalValueOption(token)) {
+            const value = argv[index];
+            if (value !== undefined && DIGITS.test(value)) {
+                index += 1;
+                parsed[OPTIONAL_VALUE_OPTIONS[token]] = value;
+            }
+            else {
+                parsed[OPTIONAL_VALUE_OPTIONS[token]] = "";
+            }
+            continue;
+        }
         if (isValueOption(token)) {
             const value = argv[index];
             // ⛔ A LONE `-` IS A VALUE, NOT AN OPTION. It is how every tool spells "the standard
@@ -121,6 +201,14 @@ export function parseArgs(argv) {
                 parsed[VALUE_OPTIONS[head]] = token.slice(equals + 1);
                 continue;
             }
+            if (isListOption(head)) {
+                append(parsed, LIST_OPTIONS[head], token.slice(equals + 1));
+                continue;
+            }
+            if (isOptionalValueOption(head)) {
+                parsed[OPTIONAL_VALUE_OPTIONS[head]] = token.slice(equals + 1);
+                continue;
+            }
         }
         if (token.startsWith("-") && token !== "-") {
             throw new NmtsError(`Unknown option: ${token}`, {

package/dist/artifact-about.d.ts

@@ -0,0 +1,49 @@
+/** The product these artefacts come from, spelled as the formats carry it. */
+export declare const PRODUCT = "NMTS";
+/** Where the recovery list's format is written down, in the copy anybody can reach. */
+export declare const RECOVERY_SPEC_URL = "https://github.com/needmoretruth/nmts-recovery/blob/main/docs/RECOVERY-MANIFEST.md";
+/** Where the envelope format is — key derivation, header layout, domain separators. */
+export declare const CRYPTO_SPEC_URL = "https://github.com/needmoretruth/nmts-recovery/blob/main/docs/CRYPTO-FORMAT-NCF3.md";
+/**
+ * Which build wrote the file.
+ *
+ * ⚠ A CLAIM, NEVER A REQUIREMENT. It names THIS PROGRAM rather than the site release, because that
+ *   is the field's own contract — what the writer says about itself — and a person holding two
+ *   copies of one account's artefacts can then tell which program made each.
+ */
+export declare const WRITTEN_BY = "nmts-cli 0.34.1";
+/** Which of the three artefacts a wrapper is. A reader holding several can sort them. */
+export type ArtifactKind = "recovery-list" | "file-list" | "recovery-kit";
+/**
+ * How a sealed payload is put together — enough for a stranger to open it with the format
+ * document and an NMTS key, and nothing else.
+ *
+ * `context` is the NCF-3 domain separator the envelope was sealed under. It is not a secret and it
+ * is not a key: it is the string a re-implementation has to pass to the same function, and one
+ * that guesses it wrong gets an authentication failure with nothing to explain it.
+ */
+export interface SealedDescription {
+    format: "ncf3";
+    context: string;
+    encoding: "base64url";
+    /** What the reader must supply. One value, and the person has it or they do not. */
+    opened_with: "nmts-account-code";
+    spec_url: string;
+}
+/** The plaintext self-description a wrapper carries. */
+export interface ArtifactAbout {
+    product: string;
+    product_url: string;
+    app_version: string;
+    artifact: ArtifactKind;
+    tool: string;
+    tool_url: string;
+    /** Where THIS artefact's format is written down. */
+    spec_url: string;
+    /** Absent on the kit, which is a text file that EMBEDS a sealed document rather than being one. */
+    sealed?: SealedDescription;
+    /** Kit only: what is inside it, so its danger is legible before it is opened. */
+    contains?: readonly string[];
+}
+/** The block for one wrapper. */
+export declare function artifactAbout(artifact: ArtifactKind): ArtifactAbout;

package/dist/autonomy.d.ts

@@ -0,0 +1,39 @@
+/** What an agent may decide without asking. */
+export type Autonomy = "default" | "auto-low" | "auto-high" | "skip-permissions";
+export declare const AUTONOMY_MODES: readonly Autonomy[];
+/** What each mode means, in the words the tool prints. One line each, no more. */
+export declare const MODE_MEANS: Readonly<Record<Autonomy, string>>;
+/**
+ * The whole explanation of one mode — what it is, what can go wrong, what is gained, and the way
+ * out. ⛔ AN AGENT THAT RECOMMENDS A MODE SHOWS THIS TEXT, whole, to the person (AGENTS.md).
+ */
+export declare function explain(mode: Autonomy): string[];
+/** The sentence a person types to turn skip-permissions on. Nobody types it by accident. */
+export declare const SKIP_SENTENCE = "NOTHING WILL ASK ME AND I ACCEPT THAT";
+/** Whether an agent, rather than a person, is taken to be driving. */
+export declare function isAgentMode(mode: Autonomy): boolean;
+/**
+ * Read a stored name, including the two this tool wrote before 2026-09-06: `off` is `default`
+ * and `auto` is `auto-low`. Anything else counts as `default`.
+ */
+export declare function modeFromStored(value: unknown): Autonomy;
+/**
+ * What this machine is set to.
+ *
+ * ⛔ Unreadable counts as `default`. The fail-safe direction for "I do not know" is the one where
+ *    somebody is still asked -- a file that switches autonomy on when it cannot be parsed is worse
+ *    than no file at all.
+ */
+export declare function currentMode(): Autonomy;
+/** When it was set, or null when it is default or unreadable. */
+export declare function setAt(): string | null;
+/** Write the choice down, with the date and the version that was asked. */
+export declare function setMode(mode: Autonomy, version: string, now: Date): void;
+/**
+ * The line every run prints when a mode is on.
+ *
+ * ⛔ IT IS PRINTED EVERY TIME, not once. A setting that stops announcing itself is a setting people
+ *    forget they turned on, and this one decides whether anybody is asked before money is spent.
+ *    ⚠ It goes to stderr: stdout belongs to whatever is reading this tool's output.
+ */
+export declare function announcement(mode: Autonomy): string | null;

package/dist/autonomy.js

@@ -1,21 +1,31 @@
-// How much this machine's owner has said an agent may decide on its own.
+// How much an agent driving this tool may decide on its own — the four modes.
 //
-// ⛔ THIS IS A DIFFERENT AXIS FROM CONSENT, and mixing the two would make both harder to reason
-//    about. A consent key says "this machine agreed that this tool may do X" -- it is about the
-//    CAPABILITY, it is recorded, and it stands until it is revoked. A mode says "an agent driving
-//    this tool may decide for me" -- it is about WHO CHOOSES, and it changes nothing about what
-//    the tool is able to do. They are stored in different files for that reason: a mode is not a
-//    sixth consent, and the count of consents is a number this package deliberately holds down.
+// ⛔ THIS IS A DIFFERENT AXIS FROM UNLOCKING, and mixing the two would make both harder to reason
+//    about. An unlock says "this machine's owner opened this capability" -- it is about WHAT the
+//    tool may do, it is recorded, and it stands until it is locked again. A mode says "an agent
+//    driving this tool may decide for me" -- it is about WHO CHOOSES, and it opens nothing that is
+//    locked. They are stored in different files for that reason.
 //
-// ⛔ NOTHING IS ON BY DEFAULT, AND TURNING ONE ON TAKES A FLAG THAT SAYS SO. The person is the one
-//    who bears what an unattended agent does with their files and their money, so the sentence
-//    that turns it on has to be one nobody types by accident.
+// ⛔ THE FOUR, AND WHAT EACH ONE CHANGES (owner, 2026-09-06). Every act this tool performs carries a
+//    risk tier (`risk.ts`: none · low · medium · high · ultra-high), and a mode decides which tiers
+//    go ahead without a person:
+//      default          a person is at the terminal. none runs; everything else is asked about;
+//                       high is locked until unlocked; ultra-high takes a typed sentence.
+//      auto-low         the agent judges whether the person asked for it, or whether it is a
+//                       reasonable thing to do unasked. none and low run; medium is the agent's
+//                       call (the code does not stop it, the instructions say to ask); high is
+//                       asked about AND locked; ultra-high never.
+//      auto-high        the same limits in code as auto-low. The instructions ask the agent to
+//                       reason more autonomously — for a model the person judges able to keep
+//                       itself safe. What differs is the instructions, not the tool.
+//      skip-permissions the person has left the chair. Nothing is refused and nothing asks;
+//                       ultra-high still demands a written reason, kept in the run log.
 //
-// ⛔ WHAT A MODE DOES NOT DO: it does not grant a consent, and it cannot grant itself. Every
-//    capability that costs money or cannot be undone is still recorded as its own agreement. What
-//    `skip-permissions` changes is WHO MAY RECORD IT -- with it on, an agent may run the grant
-//    command, which without it the instructions forbid. The record still says what was agreed and
-//    when, so a person reading it afterwards sees the same thing either way.
+// ⛔ A MODE IS SWITCHED AT A TERMINAL, BY A PERSON, and that is the lock: the command refuses when
+//    stdin is not a terminal, which is how an agent's subprocess usually arrives. It is not a
+//    perfect lock — a pseudo-terminal can be made — so the instructions say the same thing in
+//    words: an agent may RECOMMEND a mode, with the full explanation, and never turn one on.
+//    Turning one OFF (`nmts mode default`) needs no terminal: the safe direction is never harder.
 //
 // ⚠ AND WHAT NO COMMAND-LINE TOOL CAN DO: tell whether a person or a program typed this. The
 //   protection here is that the choice is explicit, written down, dated, and announced on every
@@ -23,25 +33,94 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { configDir, modesAreEnforced } from "./credentials.js";
-export const AUTONOMY_MODES = ["off", "auto", "skip-permissions"];
+export const AUTONOMY_MODES = ["default", "auto-low", "auto-high", "skip-permissions"];
 /** What each mode means, in the words the tool prints. One line each, no more. */
 export const MODE_MEANS = {
-    off: "The agent asks you before anything that has not been agreed to. This is the default.",
-    auto: "The agent decides whether you asked for it, or whether it is fine to do unasked, and goes ahead.",
-    "skip-permissions": "The agent goes ahead. There is no judgement step and nothing waits for you.",
+    default: "A person is asked before anything but reading and tidying. This is the default.",
+    "auto-low": "The agent decides whether you asked for it, or whether it is fine to do unasked, and goes ahead " +
+        "with low and medium acts. High acts still ask and stay locked; irreversible ones are refused.",
+    "auto-high": "Like auto-low, but the agent is told to reason for itself more — for a model you trust to keep " +
+        "itself safe. The tool refuses exactly what auto-low refuses.",
+    "skip-permissions": "Nothing asks and nothing is refused. You have left the chair. Irreversible acts still need a " +
+        "written reason, kept in the run log.",
 };
-/** The flag that has to be typed to turn a mode on. Spelled out so nobody types it by accident. */
-export const RISK_FLAG = "--i-accept-the-risk";
+/**
+ * The whole explanation of one mode — what it is, what can go wrong, what is gained, and the way
+ * out. ⛔ AN AGENT THAT RECOMMENDS A MODE SHOWS THIS TEXT, whole, to the person (AGENTS.md).
+ */
+export function explain(mode) {
+    const off = `Turn it off at any time: \`nmts mode default\`.`;
+    switch (mode) {
+        case "default":
+            return [
+                `default — ${MODE_MEANS.default}`,
+                `What happens: reading, downloading, listing, moving, renaming, labelling run at once. Anything`,
+                `that changes or spends is asked about (y/N here, or --yes from an agent that asked you).`,
+                `High acts — sharing, signing with the wallet, signing devices out, exposing the NMTS key — are`,
+                `locked until you unlock them (\`nmts unlock\`). Erasing the account or files takes a typed sentence.`,
+                `Risk: the smallest. Cost: an agent stops for you often.`,
+            ];
+        case "auto-low":
+            return [
+                `auto-low — ${MODE_MEANS["auto-low"]}`,
+                `What happens: the agent runs reads, tidying and reversible changes without asking, and may run`,
+                `medium acts — uploads that spend credits within the server's daily ceiling, making an API key,`,
+                `publishing your public code — when it judges you asked for them or would want them. High acts`,
+                `(sharing, wallet signing, signing devices out) are still asked about and stay locked until you`,
+                `unlock them. Erasing the account or files is refused however it is asked.`,
+                `Risk: credits can be spent and metadata changed without a question each time. What you gain:`,
+                `an agent that finishes a task instead of stopping at every step.`,
+                off,
+            ];
+        case "auto-high":
+            return [
+                `auto-high — ${MODE_MEANS["auto-high"]}`,
+                `What happens: the tool refuses exactly what auto-low refuses; what changes is the instruction`,
+                `the agent reads. In auto-low it asks itself "did they ask for this?"; in auto-high it is told to`,
+                `weigh the situation itself and act on its own judgement where a question would only delay.`,
+                `Use it only for a model you would trust with the decisions a careful assistant makes unasked.`,
+                `Risk: the same acts as auto-low, decided with less deference to you. What you gain: fewer stops`,
+                `from a capable model.`,
+                off,
+            ];
+        case "skip-permissions":
+            return [
+                `skip-permissions — ${MODE_MEANS["skip-permissions"]}`,
+                `What happens: every act runs, locked or not, asked or not. The agent may unlock things, share,`,
+                `sign with the wallet, sign devices out, erase files and the account. Erasing still needs`,
+                `--reason "<why now>", and the reason is kept in this machine's run log.`,
+                `Risk: everything this account holds and everything its wallet holds. This is the mode for "I do`,
+                `not want to be asked anything and I accept whatever happens". What you gain: nothing waits.`,
+                off,
+            ];
+    }
+}
+/** The sentence a person types to turn skip-permissions on. Nobody types it by accident. */
+export const SKIP_SENTENCE = "NOTHING WILL ASK ME AND I ACCEPT THAT";
+/** Whether an agent, rather than a person, is taken to be driving. */
+export function isAgentMode(mode) {
+    return mode !== "default";
+}
 function path() {
     return join(configDir(), "autonomy.json");
 }
-function isMode(value) {
-    return typeof value === "string" && AUTONOMY_MODES.includes(value);
+/**
+ * Read a stored name, including the two this tool wrote before 2026-09-06: `off` is `default`
+ * and `auto` is `auto-low`. Anything else counts as `default`.
+ */
+export function modeFromStored(value) {
+    if (value === "off")
+        return "default";
+    if (value === "auto")
+        return "auto-low";
+    return typeof value === "string" && AUTONOMY_MODES.includes(value)
+        ? value
+        : "default";
 }
 /**
  * What this machine is set to.
  *
- * ⛔ Unreadable counts as `off`. The fail-safe direction for "I do not know" is the one where
+ * ⛔ Unreadable counts as `default`. The fail-safe direction for "I do not know" is the one where
  *    somebody is still asked -- a file that switches autonomy on when it cannot be parsed is worse
  *    than no file at all.
  */
@@ -49,15 +128,14 @@ export function currentMode() {
     try {
         const parsed = JSON.parse(readFileSync(path(), "utf8"));
         if (typeof parsed !== "object" || parsed === null)
-            return "off";
-        const mode = Reflect.get(parsed, "mode");
-        return isMode(mode) ? mode : "off";
+            return "default";
+        return modeFromStored(Reflect.get(parsed, "mode"));
     }
     catch {
-        return "off";
+        return "default";
     }
 }
-/** When it was set, or null when it is off or unreadable. */
+/** When it was set, or null when it is default or unreadable. */
 export function setAt() {
     try {
         const parsed = JSON.parse(readFileSync(path(), "utf8"));
@@ -72,7 +150,7 @@ export function setAt() {
 }
 /** Write the choice down, with the date and the version that was asked. */
 export function setMode(mode, version, now) {
-    if (mode === "off") {
+    if (mode === "default") {
         if (existsSync(path()))
             rmSync(path(), { force: true });
         return;
@@ -91,8 +169,8 @@ export function setMode(mode, version, now) {
  *    ⚠ It goes to stderr: stdout belongs to whatever is reading this tool's output.
  */
 export function announcement(mode) {
-    if (mode === "off")
+    if (mode === "default")
         return null;
-    return `${BANNER_PREFIX}${mode} — ${MODE_MEANS[mode]} Turn it off with \`nmts mode off\`.`;
+    return `${BANNER_PREFIX}${mode} — ${MODE_MEANS[mode]} Turn it off with \`nmts mode default\`.`;
 }
 const BANNER_PREFIX = "nmts: autonomy is ";