@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/README.md

@@ -1,381 +1,291 @@
 # nmts
 
-Command-line access to [NMTS](https://nmts.me) — end-to-end encrypted storage on the Walrus
-network. For people at a terminal, and for the agents they run.
+Command-line access to [NMTS](https://nmts.me) — **NeedMoreTruthStorage**, end-to-end encrypted
+cloud storage on the Walrus network, built by one developer ([needmoretruth](https://github.com/needmoretruth)).
+For people at a terminal, and for the AI agents they run. The site is **https://nmts.me**.
 
-> **[한국어 문서](README.ko.md)**
+> **[한국어 문서](README.ko.md)** · Talk about NMTS on [Discord](https://discord.gg/pcmRkVmVZk),
+> in English or Korean.
 >
-> **Talk about NMTS — [Discord](https://discord.gg/pcmRkVmVZk).** Questions, ideas, and
-> what people are building with it. English or Korean; both are read.
-
 > **If you are an AI agent, read [AGENTS.md](AGENTS.md) instead.** It says the same things in the
-> order a program needs them, and it is the file to follow when a person points you at this tool.
-
-> **Status: early.** Built in the open, and the interface may still change before 1.0. Nothing here is a promise about a shipped feature — `nmts --help` is the current truth
+> order a program needs them.
+>
+> **Status: early.** The interface may still change before 1.0. `nmts --help` is the current truth
 > about what exists.
 
-## What NMTS is
+## 🧭 What NMTS is
 
 Storage where **the encryption happens on your machine and the keys never leave it.** The server
-receives sealed bytes and has no way to open them; the file contents, the names and the folder
-structure are all inside a sealed list only your account code opens.
+receives sealed bytes it cannot open. File contents, names and folders all live inside a sealed
+list that only your NMTS key opens.
 
-The bytes themselves live on **Walrus**, a public storage network, paid for on the **Sui** chain.
-Two consequences worth knowing before you start:
+The bytes live on **Walrus**, a public storage network, paid for on the **Sui** chain. Three
+things to know before you start:
 
 - **Storage is bought for a period, not forever.** A file has a lease. It can be extended, and
   NMTS warns before one runs out.
-- **There is no password reset.** Your account code *is* the account. It is not recoverable and it
-  cannot be changed while keeping the files — that is the same property that stops anyone,
-  including NMTS, from opening them.
+- **There is no password reset.** Your NMTS key *is* the account. It cannot be recovered or
+  changed while keeping the files. That is the same property that stops anyone, including NMTS,
+  from opening them.
+- **NMTS charges nothing.** Storage is bought from the Walrus network, for a period, from your own
+  wallet; nothing is paid to NMTS. Uploads here spend **credits**, which are storage a donation pool
+  has already paid the network for (the weekly free trial) — they are not sold. One command,
+  `nmts extend`, pays from your own Sui wallet instead, and asks for a separate agreement first,
+  because a signed purchase on a public chain cannot be reversed by anyone.
 
-There are two ways to pay: **credits**, where NMTS's treasury buys the storage and your account
-spends credits it already holds, or **your own Sui wallet**, which signs the purchase itself on a
-public chain. Uploading here always uses credits. One command uses the wallet — `nmts extend`,
-which buys more time for a file that is already stored — and it asks for a separate agreement
-before it signs, because a signed purchase is not something NMTS can reverse.
+NMTS is built and run by one developer. This tool, the encryption engine and the recovery program
+are open source under Apache-2.0; the server and the web app are not published.
 
-## Install
+## 📦 Install
 
-Node 22 or newer. One line, straight from this repository:
+Node 22.15.0 or newer. Nothing is compiled at install time and there is no native build step: the
+encryption engine is a WebAssembly module carried in the repository. It runs wherever Node runs —
+Linux, macOS, Windows, and inside a rootless container.
 
 ```sh
-npm install -g github:needmoretruth/nmts-cli
+npm install -g @needmoretruth/nmts-cli
 nmts --help
 ```
 
-That takes the default branch. To pin a version, name a tag:
-
-```sh
-npm install -g github:needmoretruth/nmts-cli#v0.17.2
-```
-
-Or from the tarball on the [latest release](https://github.com/needmoretruth/nmts-cli/releases),
-which is the same package and needs no clone:
+The same package can be installed straight from this repository, without the registry — from the
+default branch, from a pinned version, or from the tarball attached to the
+[latest release](https://github.com/needmoretruth/nmts-cli/releases):
 
 ```sh
+npm install -g github:needmoretruth/nmts-cli            # the default branch
+npm install -g github:needmoretruth/nmts-cli#v0.34.2    # a pinned version
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 
-**It is not on a package registry, and `npm install -g nmts` will not find it.** That short name
-is not available either: the registry refuses it as too close to names already published there.
-Nothing else about installing changes: the repository stays the source either way.
+The registry name carries the scope: `npm install -g nmts` finds nothing, because the registry refuses
+that short name as too close to names already published.
 
-**Nothing is compiled at install time**, and `dist/` is in this repository for that reason:
-installing straight from a repository cannot build, because npm prepares it in a staging clone
-where the compiler is not there. A committed build can drift from what produced it, so this
-repository's own checks rebuild it on every push and refuse if one byte differs.
+To work on the source instead, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-To work on it rather than install it:
+## 🔄 Staying up to date
 
 ```sh
-git clone https://github.com/needmoretruth/nmts-cli
-cd nmts-cli
-npm install
-node src/main.ts --help
+nmts update            # installs the newest release over this one
+nmts update --dry-run  # prints the versions and the command, changes nothing
 ```
 
-`npm run compile` refreshes `dist/`, and `node dist/main.js` runs it — the same file the installed
-command runs. It is called `compile` and not `build` for a reason worth knowing before renaming
-it: on npm 11, a package with a script named `build` installs from a git URL by linking npm's own
-temporary clone and then deleting it, which leaves a broken command and **reports success**.
-
-**There is no native build step and no C compiler anywhere in this**: the encryption engine is a
-WebAssembly module carried in the repository. It runs wherever Node runs — Linux, macOS,
-Windows, and inside a rootless container. Starting it costs about 80 milliseconds, and commands
-load only what they need.
+Separately, once a day after a command finishes, the tool asks the releases page which version is
+newest and remembers the answer. When a newer one exists, the next run prints one line on stderr.
+That request carries no NMTS key, no API key and no command name, and it is the only request
+the tool makes that no command asked for. Setting `NMTS_NO_UPDATE_CHECK` to anything stops both
+halves, and `nmts env` shows what the check last found.
 
-## Staying up to date
+## 🚀 First run
 
 ```sh
-nmts update
+nmts env       # what this machine is, and whether credentials are in reach. Contacts nothing.
+nmts login     # keep the NMTS key here, sealed, and take an API key
+nmts ls        # list the files
+nmts put x     # upload one file — spends credits
+nmts get x     # download one file
 ```
 
-It reads which release is newest, prints the version running and the version published, and
-installs the newer one with `npm install --global` from that release's own address. `--dry-run`
-prints the command and stops. Run from a source checkout rather than an installed copy, it
-refuses: installing would leave two copies and the PATH would decide which one runs.
-
-Separately, **once a day, after a command has finished**, it asks
-`https://github.com/needmoretruth/nmts-cli/releases/latest` which release is newest and writes the
-answer down. When that is newer than the version running, the next run prints one line on stderr
-saying so — stderr, so it cannot land in the output of `--json`.
+Run `nmts env` first on any machine you do not know — a container, a CI runner, someone else's
+laptop. It needs no credential and reports what a credential here would be exposed to.
 
-That request carries no account code, no API key and no command name: it asks for a page address,
-and what the site can see is that somebody asked for it. It is the only request this tool makes
-that no command asked for; everything else goes to the NMTS server or to the storage network
-because something needed it.
-
-Set `NMTS_NO_UPDATE_CHECK` to anything and both halves stop — the lookup and the notice.
-`nmts env` shows what the check last found, or why it did not answer.
-
-## First run
-
-```sh
-nmts env
-```
-
-It contacts nothing and needs no credential. It reports what this machine is, whether a file
-written here can actually be kept private, whether a browser could be opened, and whether it can
-already see your credentials. On anything unfamiliar — a container, a CI runner, someone else's
-laptop — run this first.
-
-## The two credentials
+## 🔑 The two credentials
 
 They do different jobs and they are not interchangeable.
 
-**The account code opens your files.** Every key in the account derives from it: the file keys, the
-sealed list, the wallet. It never goes to the server.
-
-```sh
-export NMTS_ACCOUNT_CODE_FILE=/path     # name a file holding it — the recommended way
-nmts login                              # …or keep it here, sealed under a passphrase
-export NMTS_ACCOUNT_CODE="..."          # …or hand it over directly (asks once, see below)
-```
-
-**The API key makes the server answer.** Signing in normally needs a human check that no
-command-line tool can pass; a key, made on the account screen at [nmts.me](https://nmts.me),
-waives that and nothing else. **It opens no file.**
+| | What it does | How to give it |
+|---|---|---|
+| **NMTS key** | Opens your files. Every key in the account derives from it. Never goes to the server. | `NMTS_ACCOUNT_CODE_FILE=/path` (recommended) · `nmts login` · `NMTS_ACCOUNT_CODE` |
+| **API key** | Makes the server answer. Made on the account screen at nmts.me. Opens no file. | `NMTS_API_KEY_FILE=/path` (recommended) · `NMTS_API_KEY` · `nmts login` |
 
-```sh
-export NMTS_API_KEY_FILE=/path          # name a file holding it — the recommended way
-export NMTS_API_KEY="..."               # …or hand it over directly
-nmts login                              # …and this writes down whichever it finds, or asks
-```
+`nmts ls` needs both: the API key so the server answers, your NMTS key so the answer can be opened.
 
-`nmts ls` needs both: the key so the server answers, the code so the answer can be opened.
+**The NMTS key used to be called the account code; only the name changed.** The flags, the
+environment variables (`NMTS_ACCOUNT_CODE`, `NMTS_ACCOUNT_CODE_FILE`), the config keys, the MCP
+tool and argument names, the error codes and every file format keep the names they already had, so
+nothing you have scripted breaks.
 
-`nmts login` checks a key with the server before it writes it down, so a wrong one is wrong at the
-moment it is pasted rather than at the next command. It prints the key's public handle and never
-the key itself. A key already stored is not replaced by a run that did not say so: at a terminal
-`login` asks, and where there is no terminal `nmts logout` clears what is there first.
+`nmts login` checks the API key with the server before writing it down, prints that key's public
+handle and never the key itself, and does not replace a stored API key unless the run says so.
+`nmts logout` clears what is stored.
 
-**Neither credential is ever accepted as a command-line argument.** On Linux any process can read another
-process's command line, and shells record it in history. There is no flag for either, deliberately.
+`nmts whoami --reveal` prints your NMTS key itself. It is locked until you run `nmts unlock
+reveal` once, and asked about on every run; anything that logs your terminal has your NMTS key from
+then on.
 
-## Where the code can live
+**Neither credential is ever accepted as a command-line argument.** Any process can read another
+process's command line, and shells record it in history. There is no flag for either.
 
-Four places, and the tool has an opinion about each. Nothing is unreachable: what changes is
-whether it happens by accident.
+### Where the NMTS key can live
 
 | | What it does | Asks |
 |---|---|---|
-| `NMTS_ACCOUNT_CODE_FILE=/path` | Reads the code from a file it never copies | nothing |
+| `NMTS_ACCOUNT_CODE_FILE=/path` | Reads your NMTS key from a file it never copies | nothing |
 | `nmts login` | Seals it under a passphrase at `~/.nmts/credentials.json` | nothing |
 | `nmts login --plain` | Writes it in the clear, mode 600 | once, `unsafe-code-storage` |
-| `NMTS_ACCOUNT_CODE`, holding the code | Uses it straight from the environment | once, `plain-env` |
+| `NMTS_ACCOUNT_CODE`, holding your NMTS key | Uses it straight from the environment | once, `plain-env` |
 
-**`nmts login` seals by default.** What lands on disk is not the code: opening it needs a
-passphrase, so a copy of that file in a backup, a synced folder, a container image or a stolen
-laptop is worth nothing on its own. Every command that needs the code asks for the passphrase, or
-reads it from `NMTS_PASSPHRASE`. That costs a fraction of a second and 64 MiB of memory each
-time — which is the point, because it is what makes guessing the passphrase expensive.
+A sealed NMTS key needs its passphrase for every command, from a terminal or from
+`NMTS_PASSPHRASE`. Opening it costs a fraction of a second and 64 MiB of memory, which is what
+makes guessing the passphrase expensive. A passphrase does not protect your NMTS key from anything
+running as you: on a machine where an agent runs unattended, the passphrase has to be reachable
+too. That is why the file form is the recommendation for agents — your NMTS key is never copied,
+and the permissions are the host's to set.
 
-⚠ **A passphrase does not protect the code from anything running as you.** Whatever supplies the
-passphrase can be read the same way. On a machine where an agent runs unattended, `NMTS_PASSPHRASE`
-has to be somewhere the agent can reach, and at that point the lock has its key taped beside it.
-That is why the file form — `NMTS_ACCOUNT_CODE_FILE` — is the recommendation for agents rather
-than a lesser option: the code is never copied anywhere, and the permissions are the host's to set.
+An environment variable is not private: `docker inspect` prints it, anything running as you can
+read `/proc/<pid>/environ`, every child process inherits it, and CI systems write it into logs.
+That is why using one asks once. `nmts login --env` prints the line to set and writes nothing; it is
+behind the same agreement.
 
-**An environment variable is not private, which is why using one asks.** `docker inspect` prints
-the whole environment of a container. Anything running as you can read `/proc/<pid>/environ` for as
-long as the process lives. Every child process inherits it, and continuous-integration systems
-routinely write it into a log. A variable naming a *file* has none of those, and asks nothing.
+**Under Codex, Hermes and OpenClaw an environment variable does not reach an MCP server.** All
+three clear the environment before starting one. Sign in with `nmts login` instead, or put the
+variables in the server's own `env` block. `nmts env` names the agent it can see.
 
-**`nmts login --env` prints the line to set and writes nothing** — the one command that puts the
-code on your screen, and the reason it is behind the same agreement.
+## 🤖 Before you hand this to an agent
 
-**What you do with the code outside this tool is yours.** Putting it in a note, a password manager
-or a repository is not something the tool can see, and it is not something it tries to stop. What
-it can do is make the shape *it* writes a decision somebody took on purpose.
+Your NMTS key is everything at once. A program that has it can read every file, upload,
+delete and sign with the wallet, and its requests cannot be told apart from yours. It cannot be
+rotated while keeping the account. **Use an account you would be willing to lose.**
 
-## Before you hand this to an agent
-
-Your account code is everything at once. A program that has it can read every file, upload,
-delete, and sign with the wallet — and requests made with it cannot be told apart from your own.
-It cannot be rotated while keeping the account.
-
-**Use an account you would be willing to lose.**
-
-## Commands
+## 🧰 Commands
 
 | Command | What it does |
 |---|---|
 | `nmts env` | Where this is running, and what that means. Needs nothing. |
-| `nmts login` / `logout` | Keep or remove an account code on this machine |
-| `nmts whoami` | Which account the stored code belongs to — offline, no server call |
-| `nmts expiring` | Which files run out of bought storage soon, and when |
-| `nmts extend <path>` | Buy more storage time for one file — **signs and spends from the wallet** |
-| `nmts create` | Make a NEW account and print its code once. Nothing can print it again |
-| `nmts trial` | What is left of this week's free credits. `trial apply` asks for some |
-| `nmts recovery-list` | Write the file that finds this account's bytes without NMTS |
-| `nmts kit` | Recovery kit: that list **and the account code**, together in one file |
-| `nmts sweep` | Drop trash entries past their 30 days. **Cannot be undone** — asks every run |
-| `nmts consent` | What this machine has agreed to |
-| `nmts update` | Install the newest published release of this tool |
+| `nmts login` / `logout` | Keep or remove an NMTS key and an API key on this machine |
+| `nmts whoami` | Which account the stored NMTS key belongs to — offline. `--reveal` prints your NMTS key |
 | `nmts ls` | List the files |
 | `nmts usage` | What the account holds: counts, bytes, the largest files, the trash |
+| `nmts balance` | Credits left, what they buy, and the ceilings on spending |
 | `nmts get <path>` | Download one file, decrypt it, check it |
 | `nmts pull [folder]` | Download a whole folder, or the whole account, keeping its shape |
-| `nmts push <directory>` | Upload a whole directory, keeping its shape — **spends credits** |
-| `nmts put <file>` | Encrypt one file and upload it — **spends credits** |
+| `nmts put <file>` | Encrypt one file and upload it — **spends credits**. `--deposit <n>` sets the deposit for this upload |
+| `nmts push <directory>` | Upload a whole directory, keeping its shape — **spends credits**. `--deposit <n>` applies to every file in it |
 | `nmts rm <paths>` | Move things to the trash — restorable for 30 days |
 | `nmts restore <paths>` | Bring things back out of the trash |
+| `nmts sweep` | Drop trash entries past their 30 days. **Cannot be undone** — asks every run |
+| `nmts erase <paths>` | Erase files for good — the server's record and this account's key, trash or not. A typed sentence, your NMTS key beside the API key; `--release-storage` also destroys credit-paid storage (locked until `nmts unlock release-storage`) |
 | `nmts mkdir <path>` | Make a folder, and any folder above it that is missing |
 | `nmts mv <paths> <folder>` | Move things into a folder. `/` is the top of the drive |
 | `nmts rename <path> <name>` | Give one thing a new name |
 | `nmts star` / `unstar` | Star files, or take the star off |
 | `nmts pin` / `unpin` | Hold files at the top of their folder, or let them fall back |
-| `nmts label <name> <files>` | Put one label on files. `unlabel` takes it off |
-| `nmts rebuild` | Build a file list from the server's rows, for an account with none |
-| `nmts listfile` | Write this machine's copy of the sealed file list out as a file |
-| `nmts share <path> <address>` | Give one file to another account — **withdrawing does not recall it** |
-| `nmts shares` | What was shared with this account |
+| `nmts label <name> <files>` | Put one label on files. `unlabel` takes it off; `--rename` and `--all` sweep the whole list |
+| `nmts on-collision` | What an upload does when its name is already taken |
+| `nmts padding [mode]` | How file sizes are hidden on the storage network, and change it for the next uploads |
+| `nmts deposit [credits]` | How many credits each credit-paid upload sets aside as a deposit (0 to 64, default 64), and change it |
+| `nmts tip [percent\|off]` | A standing share of every WAL payment sent to the developer as a gift (default 0). Setting it needs `nmts unlock donate`; the agreement is asked once |
+| `nmts expiring` | Which files run out of bought storage soon, and when |
+| `nmts losses` | Storage NMTS bought for you that the daily check could not find on the chain. `--recheck <id>` asks again; `--dismiss <id>` takes a line off |
+| `nmts extend <path>` | Buy more storage time for one file — **signs and spends from the wallet** |
+| `nmts wallet` | The account's wallet address, and its SUI and WAL balances. Never signs |
+| `nmts wallet activity` | The wallet's recent transactions, named only where the chain proves it. Never signs |
+| `nmts wallet storage` | The storage resources (size × time) the wallet holds outside any file. Never signs |
+| `nmts wallet storage split <id> --size <n>\|--epochs <n>` · `merge <id> <id>` · `transfer <id> <address>` | Cut, join or hand over a storage resource — **signs**, under the wallet unlock (`transfer` needs scope `all`). No file goes with a transfer: size and remaining time only |
+| `nmts wallet send <SUI\|WAL> <amount\|max> <address>` | Send coins to an address — **signs and spends from the wallet**. Prints the review; sends only with `--yes` |
+| `nmts wallet swap <SUI\|WAL> <amount\|max>` | Swap one coin for the other on DeepBook or Bluefin — **signs and spends from the wallet**. Without `--venue` prints both quotes and stops; swaps only with `--yes` |
+| `nmts wallet donate <SUI\|WAL> <amount>` | A voluntary gift to the developer, in either coin — **signs and spends**. Locked until `nmts unlock donate`, and `--yes` every run |
+| `nmts wallet hall [--name <name>\|--remove]` | The gift hall of fame; `--name` lists you by a name you choose, signed by your wallet |
+| `nmts trial` | What is left of this week's free credits. `trial apply` asks for some |
+| `nmts create` | Make a NEW account and print its NMTS key once. Nothing can print it again. With no verified API key on this machine it makes the NMTS key here, prints an address, and waits while a person opens it, types that NMTS key and passes the human check — the account exists the moment they finish. `--no-wait` prints the address and stops |
+| `nmts verify` | Ask a person to pass the check that opens this account's limits. Only the account holder can: signed in to this account in that browser, or typing its NMTS key there |
+| `nmts public-code` | The code other accounts send files to. `--publish` makes it reachable |
+| `nmts share <path> <address>` | Give one file to another account — **withdrawing does not recall it**. Locked until `nmts unlock share`; every share stops and `--yes` answers for that one file |
+| `nmts shares` | What was shared with this account; `--sent <path>` shows who one file went to |
 | `nmts receive <id>` | Download one file somebody shared with this account |
 | `nmts unshare <id>` | Withdraw a share you sent, or remove one you were sent |
-| `nmts wallet` | The account's wallet address, and its SUI and WAL balances |
-| `nmts verify` | Ask a person to pass the check that opens this account's limits |
+| `nmts rebuild` | Build a file list from the server's rows, for an account with none |
+| `nmts rollback` | Put the previous version of the file list back — locked until `nmts unlock rollback`, `--yes` every run |
+| `nmts listfile` | Write this machine's copy of the sealed file list out as a file |
+| `nmts recovery-list` | Write the file that finds this account's bytes without NMTS |
+| `nmts kit` | Recovery kit: that list **and your NMTS key**, together in one file |
+| `nmts recovery` | Download the standalone program that reads files back without NMTS |
+| `nmts unlock` / `nmts lock` | What this machine has unlocked; `unlock <key>` opens one (a person, at a terminal), `lock <key>` closes it. `consent` is the older name |
+| `nmts mode` | How much an agent driving this tool may decide without asking |
+| `nmts support send` | Send a report to the developer — a bug, an error, an idea, a question. `--attach-log` adds the last runs, redacted |
+| `nmts support list` / `show <code>` / `reply <code>` | Read the answers, and write back in the same thread |
+| `nmts update` | Install the newest published release of this tool |
+| `nmts notices` | What NMTS has posted: interruptions, incidents, and the warning before new Terms take effect. `notices <id>` prints one; `--save <id>` keeps it as a dated file |
+| `nmts terms` | The Terms of Service in force. `--lang ko` for Korean, `--board` for the message board's terms, `--save` to keep a copy |
+| `nmts privacy` | The Privacy Policy in force. `--lang ko`, `--save` to keep a copy |
+| `nmts delete-account` | A **person** erases this account's server record — irreversible. Needs your NMTS key and a typed sentence; refused in the auto modes, and under skip-permissions only with `--reason` |
+| `nmts accept-terms` | Accept a new version of the Terms after reading it: a person types the versions, or an agent relays them with `--accept-terms <v> --accept-privacy <v> --yes` after asking |
+| `nmts key new` | Make an API key for this account with your NMTS key alone — no browser. `--scopes read,write,spend`, `--days <n>`. The new API key is stored as this machine's credential; `--print` also prints it once |
+| `nmts devices` | The devices signed in to this account. `--sign-out <id>` or `--sign-out all` ends one or all of them — needs your NMTS key, locked until `nmts unlock sign-out`, asked every run |
 | `nmts mcp` | Serve a subset of the above as tools over the Model Context Protocol |
 | `nmts s3` | Serve the drive to any S3 program, on this machine only |
 
-`ls` takes `--json` and `--all` (include the trash). Trashed entries are hidden by default and the
-count always says how many were hidden. `--find <text>` keeps only files whose name contains the
-text; folders appear only where they hold a match, and the listing says out loud what the query
-left out. `--sort name|size|date` and `--desc` change the order.
-
-`share` needs an address, which the other account reads off their own account screen — there is no
-directory and no name lookup, so a mistyped address is caught here by the check symbol built into
-it rather than by asking the server about somebody. **Withdrawing a share stops further downloads
-and cannot reach a copy they have already taken.** That is what handing somebody a file means, and
-it is why sharing asks for an agreement the first time.
-
-`pull` fetches each file on its own: one that will not come back is named at the end and the rest
-are still on disk, because refusing the whole thing over one file is how somebody runs it twenty
-times and loses the same nineteen files each run. Files already in the destination are **skipped
-and counted**, never replaced — `--force` replaces, and that cannot be undone.
-
-`push` is the other direction, and it behaves differently on purpose. `pull` costs nothing, so it
-carries on past a file that will not come back; `push` **spends**, so it stops at the first failure
-and says what is already uploaded — those files are real and paid for, and running the same command
-again sends only the rest. Files whose name is already in the destination are **skipped**, which is
-what makes running it again safe: this tool never replaces a file, so without that a second run
-would pay for numbered copies of everything. Names beginning with a dot are left alone unless
-`--hidden` is given, because a directory of source code carries its credentials in exactly those
-files and an upload goes to a public storage network. Symbolic links are not followed.
-
-`rm`, `restore` and `mv` take several paths and make **one** list write. A path that names nothing
-stops the whole run before any server row is touched: doing four of five and exiting 0 reads as
-"finished", and which one was missed can only be found by comparing the drive.
-
-`rebuild` is for an account whose sealed list is gone but whose files are still stored. It rebuilds
-from the server's own rows — the file keys, the hashes, the dates, the sizes and what was in the
-trash all come back; the names, the folders and the arrangement do not, and it says so. It writes
-nothing without `--yes`, and it refuses outright if a list already exists.
-
-`wallet` reads; it never signs, sends or spends. The address is derived on this machine from the
-account code, so `nmts wallet address` needs no network at all. A balance that could not be read is
-reported as unread — not as zero.
-
-`get` takes `--out` and `--force`. It refuses rather than writing a half-right file: a part that
-will not decrypt, parts that do not add up, or a whole-file hash that does not match all leave
-nothing at the name you asked for. A file on disk is a claim that it is the file. The bytes are
-written as they arrive, under a temporary name in the same directory, and that file is renamed
-into place only once the whole-file hash matches. The file is never held in memory; one part
-at a time is, so what a machine needs is the part size the uploader chose rather than the size
-of the file. A download that fails takes its temporary file with it.
-
-`--out -` sends the file to whatever is reading this program instead of writing it, so reading one
-stored file need not leave a copy on the disk. Everything a person reads goes to stderr in that
-mode. It refuses to send bytes a terminal would act on — redirect or pipe it. A pipe has no
-rename, so that mode proves the whole file before it sends a byte, which means holding it: above
-64 MiB it refuses and says to use `--out <name>` instead.
-
-`put` takes `--dry-run`, `--name` and `--to`:
+### Listing and fetching
 
-```sh
-nmts put report.pdf --dry-run       # what it would cost. Sends nothing, charges nothing.
-nmts put report.pdf --to notes      # into an existing folder
-nmts put film.mov --part-size 256MiB  # bigger parts: fewer purchases, more memory
-```
+`ls` takes `--json`, `--all` (include the trash; the count always says how many were hidden),
+`--find <text>` (files whose name contains the text, with the folders that hold them), `--sort
+name|size|date` and `--desc`.
 
-One credit per started mebibyte, printed before anything is spent. A name already taken in that
-folder is numbered (`report (2).pdf`) rather than replacing what is there — NMTS keeps no previous
-versions, so replacing would be permanent.
+`get` takes `--out` and `--force`. It never leaves a half-right file: the bytes are written under a
+temporary name in the same directory and renamed into place only once the whole-file hash
+matches. One part is held in memory at a time, not the file. `--out -` sends the file to stdout
+instead of writing it, with everything a person reads on stderr; a pipe cannot be taken back, so
+that mode proves the whole file first and refuses above 64 MiB.
 
-A file larger than one part is split, and **each part is bought separately**. The file is read a
-slice at a time, so its size is not bounded by memory; the part size is (64 MiB by default). Each
-part is written down before its own purchase, so a run that stops partway is finished by running
-the same command again — it buys only the parts that were never bought.
+`pull` fetches each file on its own. One that will not come back is named at the end and the rest
+stay on disk. Files already in the destination are skipped and counted; `--force` replaces them.
 
-### `nmts balance` and `nmts public-code`
-
-`balance` asks the server what this account can still pay for: credits left, the same number said
-as bytes so it means something, how much is already held, and the ceilings on spending. It is not
-the same question as `usage` — that one adds up the sealed file list and answers "what do I have",
-this one reads the ledger and answers "what can I still buy". It does not read the storage
-network's clock, so for *when* stored files expire it points at `nmts expiring` rather than
-printing a second deadline from a different source.
-
-`public-code` prints the value other accounts send files to — the same **public code** the browser
-shows on the account screen, in the same grouped form — and says whether it has been published.
-Until it is published nobody can send to you: a sender needs the key behind it, and the server is
-where they look. `nmts public-code --publish` writes it.
-
-That write is permanent: it cannot be withdrawn or changed. It is also not a choice — it comes
-from your account code, so the same account code produces the same public code on any machine, and
-the server refuses one that is not the fingerprint of its own key. If the server already holds a
-*different* public code for this account, the command stops and says what that means: the account
-code on this machine is not the one the account was made with.
-
-⛔ It is not your account code. That one opens every file you have and is never given to anybody;
-this one is meant to be given away and opens nothing on its own.
-
-Sending a file publishes it as a side effect, because a share cannot exist without one. Receiving
-is the case this command is for.
-
-### `nmts recovery` — fetch the recovery program
-
-The separate recovery program restores files from the storage network with your account code, a
-recovery list and nothing else — no NMTS server involved. Until now getting it meant installing a
-Rust toolchain and building it, which is a fair ask of somebody auditing it and an unfair one of
-somebody who has just lost access to their files.
+### Uploading
 
 ```sh
-nmts recovery --out ~/tools
+nmts put report.pdf --dry-run          # what it would cost. Sends nothing, charges nothing.
+nmts put report.pdf --to notes         # into an existing folder
+nmts put film.mov --part-size 256MiB   # bigger parts: fewer purchases, more memory
 ```
 
-It works out which executable this machine needs, fetches the checksum file for the release first
-and takes the release's own name out of that request, then fetches the executable **from that same
-release** so the two can never come from different ones. The bytes are hashed and compared before
-anything is made runnable; a mismatch deletes the file and refuses. It never replaces a file
-already at that name without `--force`, and it never puts anything on your PATH.
-
-It prints the release, the address it came from and the hash, and says plainly what that check
-does and does not prove: it proves the bytes are the bytes that release published; it proves
-nothing about who published the release. The source is in the open and so is the workflow that
-built it — that is the part worth checking.
-
-## The check a person has to pass
+One credit per started mebibyte, printed before anything is spent. A name already taken in that
+folder gets a numbered copy (`report (2).pdf`) unless `nmts on-collision` says otherwise; NMTS keeps
+no previous versions, so replacing is permanent. A file larger than one part (64 MiB by default) is
+split and each part bought separately; a run that stops partway is finished by running the same
+command again, which buys only the parts that were never bought. The same is true after any
+interrupted upload: the retry costs nothing more.
 
-An API key makes the server answer; it does not stand in for somebody being there. The server
-keeps that as a separate question — has anybody checked lately that a person is behind this
-account — and while the answer is no, the account still works under tighter limits, with some
-requests refused outright.
+`--pay wallet` buys the storage **from the wallet your NMTS key derives** instead of from credits:
 
 ```sh
-nmts verify --status   # is the check live, and until when?
-nmts verify            # prints a short code for a person to type at nmts.me, then waits
+nmts put film.mov --pay wallet --dry-run            # the review: WAL price, tip, fee, balances, days. Signs nothing
+nmts put film.mov --pay wallet --epochs 6           # six of the storage network's epochs (default 2)
+nmts put film.mov --pay wallet --storage fit        # use a storage resource the wallet already holds, cut to size
 ```
 
-`nmts verify` cannot pass the check for you, and neither can an agent running it: that is what is
-being checked. It prints a code and an address, and waits until the code is used or stops working.
-Ctrl-C ends the waiting and not the code.
-
-It prints the moment the check **ends** rather than a number of days, because the window ends on a
-boundary of the server's own weeks — one passed shortly before a boundary is a short one, and the
-absolute moment is the only honest way to say that.
-
-## Names, folders and the trash
+The order is the safety: the file is planned into the same parts, the chain quotes each part in WAL
+and the relay's tip in SUI, the register transaction is dry-run for its fee, both balances are read,
+and the review is printed — the term as epochs and as days — before the `wallet` agreement (scope
+`storage`) is held against the total and anything is signed. A wallet known to be short is refused
+with the two numbers; a balance that could not be read is said as unread, not as zero. Each part
+takes two signatures, register and certify; a run that stops partway is finished by running the same
+command again, which signs nothing twice. `--storage fit|whole|<object id>` uses a free storage
+resource the wallet holds (`nmts wallet storage` lists them) for a one-part file: `fit` cuts it to the
+part's encoded size and leaves the rest free, `whole` binds all of it with the file, and the review
+says in bytes which. Without `--storage` new storage is bought; the review only mentions what the
+wallet holds. The server records the file as stored on the wallet's own storage, and `nmts extend`
+can extend it. A wallet-paid upload does not carry the recovery list's storage-network copy,
+whichever way the account's switch is set — today only the browser's small-file uploads do. `push
+--pay wallet` does the same one file at a time.
+
+`push` uploads a directory and **stops at the first failure**, saying what is already uploaded.
+Files whose name is already in the destination are skipped, so running it again is safe. Names
+beginning with a dot are left alone unless `--hidden` is given, and symbolic links are not followed.
+
+`nmts deposit` shows how many credits each credit-paid upload sets aside as a deposit, and `nmts
+deposit <n>` changes it for every device's next uploads (0 to 64, default 64). The deposit pays the
+chain fee of a later operation on that file — releasing its storage early, for instance — measured
+rather than spent whole, and what is left comes back when the storage period ends. `put --deposit
+<n>` and `push --deposit <n>` set it for one run. `--deposit 0` sets nothing aside: that file still
+releases, but pays twice the same fee out of the balance at that moment, and is refused with both
+numbers named when the balance cannot cover it.
+
+`nmts padding` shows how file sizes are hidden, and `nmts padding standard`, `nmts padding pow2` or
+`nmts padding off` changes it for every device's next uploads (`off` stores the exact size: the
+file's length is visible to the network and to anyone who reads the blob, for about 1 % less storage). Anyone can read the size of a piece on the storage
+network; blank bytes make that size one of a set of fixed values. Powers of two hide more and cost
+more storage on average.
+
+### Names, folders and the trash
 
 ```sh
 nmts mkdir photos/2026/august   # makes all three if they are missing
@@ -385,38 +295,130 @@ nmts rm photos/2026             # to the trash, with every file under it
 nmts restore photos/2026
 ```
 
-**None of these costs anything or asks anything.** A name, a folder and a parent live only in your
-sealed file list — the server holds an id, a size and a time, and has no place to put a name. So
-renaming and moving are invisible to NMTS, instant, and free.
+None of these costs anything or asks anything: a name, a folder and a parent live only in your
+sealed file list, and the server holds no place to put a name. `rm` never destroys; each trashed
+file keeps its own thirty-day clock. The command that erases for good is deliberately not in this
+tool. A path is matched whole (`photos/a.jpg` is not `a.jpg`), and a path that matches two entries
+is refused rather than resolved. `rm`, `restore` and `mv` take several paths in one write; a path
+that names nothing stops the whole run before anything is touched.
+
+`nmts label --rename <old> <new>` renames a label on every file that carries it, and
+`nmts unlabel <name> --all` takes it off all of them. Both change only the file list.
+
+### Money and time
+
+`balance` answers "what can I still buy": credits left, said as bytes too, and the ceilings on
+spending. `usage` answers "what do I have". `expiring` says when stored files run out.
+
+`extend` buys more time for a stored file **from the wallet your NMTS key derives**, on a public
+chain. It is locked until you unlock `wallet`, which names a scope (`storage`, or `all` for exchanging and
+sending too), runs out after at most 30 days, and can carry a ceiling on what the tool signs away —
+`nmts unlock wallet --days 7 [--scope all] [--cap-wal 10 --cap-sui 0.1]`. It takes
+`--dry-run`, which touches no key. Before the agreement it reads the wallet and dry-runs the transaction: the price, the chain
+fee (SUI) and both balances are printed, and a wallet known to be short is refused with the two
+numbers rather than signed. `wallet` only reads: the address is derived on this machine, and a balance that could not be
+read is reported as unread, not as zero. `wallet address --qr` draws the address as a code a phone
+can scan. `wallet activity` lists the newest transactions with the same names the browser gives
+them (seal, extend, erase, exchange, send, receive — otherwise "other", never a guess); gifts to the
+developer show as sends there, because the tool does not know that address. `wallet storage` lists
+the storage resources the wallet holds outside any file — what deleting a file from the network
+gives back — and whether each can be used now. `wallet send` moves SUI or WAL to an address: it
+reads both balances, judges the address and the amount by the browser's own rules, dry-runs the
+transfer for its fee, prints the review with the whole address, and signs only with `--yes` and
+under a `wallet` agreement of scope `all`. `max` sends everything that can be sent (SUI keeps a
+reserve back for fees); `--fee-cap` puts a ceiling on the fee. A transfer cannot be undone. `wallet swap`
+turns SUI into WAL or WAL into SUI on one of the two venues the browser app offers on mainnet,
+DeepBook and Bluefin, with the same transaction the browser builds: your wallet signs, the outputs
+come back to it, and NMTS is not a party and takes nothing. Without `--venue` it reads both
+venues' quotes at the same moment, prints them side by side — what comes out, the venue's fee as
+measured from the quote (or "could not be measured", never a guessed figure) — and stops: neither
+is a default and the tool recommends neither; any other exchange may be used instead. With
+`--venue deepbook|bluefin` it prints the review: the quote, the least it will accept
+(`--slippage-bps`, 1 to 5000, default 50), the chain fee from a dry run, `--fee-cap` if given, and
+how far the quote sits from the site's reference price when one can be read (said as uncompared
+when none can). A slippage under 10 or over 200 bps, a fee cap far from the measured fee, or a
+quote more than 3% from the reference price is refused, even with `--yes`; `--accept-extremes`
+goes on anyway, and only a person may say it (refused while a mode is on). The swap needs `--yes`
+and a `wallet` agreement of scope `all`; the chain gives what it gives, never less than the
+minimum, and a swap that would give less fails on chain with the fee spent. On testnet the one
+rail is the official Walrus exchange, SUI→WAL only, at the rate read off its object. `wallet donate` is a voluntary gift to
+the developer, to the address the server publishes (the same one the wallet screen's card shows).
+It is locked until you run `nmts unlock donate`, needs `--yes` on every run, and is outside the
+`wallet` unlock and its ceiling. It says, before signing, that the gift is voluntary, buys nothing, is
+non-refundable and cannot be undone, and that the transaction id is the only proof. `nmts tip 2.5` makes
+2.5 % of every WAL payment (an upload paid by wallet, an extension) a standing gift, sent right after the
+payment without a question; `nmts tip off` stops it, and it is outside the `wallet` ceiling.
+
+### Sharing
+
+`share` needs the other account's public code, read off their account screen. There is no
+directory and no name lookup; a mistyped code is caught by its own check symbol. Withdrawing a
+share stops further downloads and cannot reach a copy already taken, which is why sharing asks
+for an agreement the first time.
+
+`public-code` prints the value other accounts send files to and says whether it is published.
+Until it is published nobody can send to you. `--publish` writes it, permanently: it derives from
+your NMTS key, so it cannot be chosen or changed. It is not your NMTS key, and it opens
+nothing on its own.
+
+`nmts shares --sent <path>` lists who one file was shared with — the recipient address, since when,
+and the share id `unshare` takes.
+
+### Recovery
+
+`recovery-list` writes the encrypted file that locates your bytes on the storage network; it holds
+no NMTS key. `kit` writes that list together with your NMTS key in one file, so whoever
+holds a kit holds the account. `recovery` downloads the standalone recovery program for this
+machine, checks it against the release's checksum file before making it runnable, and never puts
+anything on your PATH. `rebuild` reconstructs a file list from the server's rows for an account
+that has lost its own: keys, hashes, dates and sizes come back; names and folders do not.
+
+`nmts rollback` puts the previous version of the file list back as the current one, for the case
+where the current one will not open. Files the newer version added are out of the list afterwards —
+their bytes are still stored, and `nmts rebuild` finds files the list does not name. It is locked
+until you run `nmts unlock rollback`, and needs `--yes` on every run.
+
+### When storage goes missing
+
+`nmts losses` lists the storage objects NMTS bought with your credits that the daily check could not find on the chain — the object id and the day a check first missed it. There is no file name: the server cannot pair the two, and NMTS cannot see the file. `nmts losses --recheck <id>` asks the chain again now. `nmts losses --dismiss <id>` takes a line off once you have read it; it asks once (a medium act — in an auto mode, the agent's judgement). The incident stays in a record that names nobody; the same finding is posted on the notice board by day.
+
+### The check a person has to pass
+
+An API key makes the server answer; it does not stand in for somebody being there. While nobody
+has checked in lately, the account still works under tighter limits, and a few requests are
+refused outright.
 
-`rm` never destroys: it moves one thing to the trash, where it stays restorable for thirty days.
-The command that erases for good is deliberately not in this tool — a verb with no undo belongs to
-a person at a browser. Trashing a folder trashes what is under it, and each file keeps its own
-thirty-day clock, so restoring the folder does not resurrect something you threw away last week.
+```sh
+nmts verify --status   # is the check live, and until when?
+nmts verify            # prints a short code for the account holder to type at nmts.me, then waits
+```
 
-A path is matched **whole**: `photos/a.jpg` and `a.jpg` are different things, and a path that
-matches two entries is refused rather than resolved to whichever came first.
+Neither the tool nor an agent can pass the check. It prints the moment the check ends rather than
+a number of days, because the window ends on a boundary of the server's own weeks.
 
-If an upload is interrupted after the credits move, **running the same command again finishes it**
-and costs nothing more. The sealed bytes and the reservation are written down before the money
-moves, so a retry pushes exactly the blob that was bought rather than buying a second one.
+## What it stops to ask about
 
-## Containers
+Every act has a tier. **None** (listing, fetching, folders, marks) never asks. **Low** (the trash,
+a setting, a report) and **medium** (uploading, publishing the public code, a new key) ask once
+per run — y/N at the terminal, or `--yes`. **High** (signing with the wallet, giving another
+account a file, revealing or storing your NMTS key unsealed) is locked until you run `nmts unlock
+<key>` once on this machine, and then still asks on every run. **Ultra-high** (erasing the
+account) is a typed sentence. `nmts unlock` lists the keys; each unlock prints what it opens, what
+could go wrong and what it does not cover before it asks. `nmts help <command>` prints any
+command's document, with its tier at the top.
 
-It runs unchanged in Docker and Podman, rootless.
+## 🐳 Containers
 
-There is no image published anywhere, but this repository has a `Dockerfile`, so building one is a
-single command. Both container tools are built and run on every push to this repository, so this is
-a claim you can check rather than one you have to take.
+It runs unchanged in Docker and Podman, rootless. There is no published image; this repository has
+a `Dockerfile`, and both container tools build and run it on every push.
 
 ```sh
 docker build -t nmts .        # or: podman build -t nmts .
 docker run --rm nmts --version
 ```
 
-The image runs as an ordinary user, and it writes what it stores to `/config` — a directory it
-creates for that user, so mounting a volume there works. Mounting a volume on a path an image does
-not have gets you a root-owned volume and a tool that cannot write one byte into it.
+The image runs as an ordinary user and writes to `/config`, which it creates, so a volume mounted
+there works. Give credentials as files, never as environment variables inside a container:
 
 ```sh
 printf '%s' "$CODE" > /tmp/nmts-code && chmod 600 /tmp/nmts-code
@@ -429,101 +431,41 @@ docker run --rm \
   nmts ls
 ```
 
-⚠ **Naming a credential file the container does not have is a hard stop, not a fall-through.**
-`NMTS_API_KEY_FILE` pointing at nothing exits 3 before any request — which is the right behaviour
-and the reason both mounts are above.
-
-### Uploading from a container needs one more thing
-
-The agreements this tool asks for once are a file in its config directory, and a container that is
-removed takes that file with it — so a fresh container can list and download and will refuse to
-upload, every time. Two ways round it, and both are ordinary:
-
-```sh
-# either bake the agreement into the image
-RUN nmts consent grant spend
-
-# or keep the config directory outside the container
-docker run --rm -v nmts-config:/config … nmts put file
-```
-
-The image already points this tool at `/config`, so a volume mounted there is all the second one
-needs. On an image of your own, `NMTS_CONFIG_DIR` moves everything this tool writes — the
-agreements, the stored credentials, the once-a-day update check — to a directory you choose.
-`nmts env` reports where it landed and whether that directory survives the container being removed.
-
-**Do not put the account code in an environment variable inside a container.** The whole
-environment is visible to anyone who can inspect it — `docker inspect` prints it. A variable
-holding a *path* gives that reader a filename and nothing else. `NMTS_ACCOUNT_CODE_FILE` works
-with `--secret` mounts, tmpfs, and ordinary bind mounts.
-
-`nmts env` tells you which container runtime it is in, whether root here is root on the host, and
-whether the directory it would write to survives the container being removed.
-
-## What it stops to ask about
+A credential file that is named but missing is a hard stop (exit 3) before any request.
 
-Five things, once per machine: **spending credits**, **storing the account code unsealed**, **using
-it from a plain environment variable**, **giving another account one of your files**, and
-**signing with the wallet**. Each prints what would happen, what could go wrong, and the one
-command that agrees.
-
-The last of those belongs to one command: `nmts extend`, which buys more storage time for a file
-that is already stored. Everything else here is paid for with credits, which NMTS issues and can
-put right; that one signs a purchase on a public chain, and nobody — NMTS included — can reverse
-it. That is why it has an agreement of its own rather than sharing the one for spending.
-
-Nothing else asks *once per machine*. One command asks *every run* instead: `nmts sweep`, which
-drops trash entries whose thirty days have run out. That destroys this account's copy of the key
-for those files, so a grant given once would make every later sweep silent. Listing, downloading,
-renaming and moving never stop for anyone.
-
-`nmts consent` shows what has been agreed to and can take it back.
+Unlocks and the mode live in the config directory, and a container that is removed takes them
+with it. A fresh container lists and downloads freely; an upload asks, so a script passes `--yes`,
+and anything locked (the wallet, sharing) needs the config directory kept outside the container
+(`-v nmts-config:/config`) where a person unlocked it once. On an image of your own, `NMTS_CONFIG_DIR` moves everything the tool
+writes to a directory you choose; `nmts env` reports where it landed and whether it survives.
 
 ## Serving the drive to S3 tools
 
-`nmts s3` starts a server on this machine that speaks the S3 protocol. Point rclone, the AWS CLI, or
-any backup program that already knows S3 at it, and it lists and downloads this account's files.
+`nmts s3` starts a server on this machine that speaks the S3 protocol, so rclone, the AWS CLI or
+any backup program that knows S3 can list and download this account's files.
 
 ```
 $ nmts s3
   This account's drive is being served at http://127.0.0.1:9000, to this machine only.
-
   endpoint        http://127.0.0.1:9000
   bucket          drive
   access key id   NMTS…
   secret key      …
 ```
 
-- **One bucket, named `drive`.** A key is the file's path without the leading slash, so
-  `photos/a.jpg` in the drive is `photos/a.jpg` here. Folders come back as common prefixes,
-  including empty ones — this drive has real folders and hiding them would describe a different
-  drive from the one in the browser.
-- **The credentials are made when the command starts and are stored nowhere.** They stop working
-  when it stops.
-- **It listens on 127.0.0.1, and there is no option to change that.** One signature stands between
-  a request and every file in the account, and the key it checks was printed on a terminal.
-- **Uploading and deleting work, and both need the spending agreement.** Uploading spends credits,
-  so a machine that has not run `nmts consent grant spend` serves the drive read only and says so
-  — every write is refused with that sentence rather than answered.
-- **Deleting puts a file in the trash**, where it stays recoverable for thirty days.
-- **A key that already holds the SAME file is answered `200`, and nothing is sent.** What is
-  compared is the file's content, not its name: every upload records a hash of the plaintext,
-  sealed so only this account can read it, and the gateway compares the arriving bytes against it.
-  So a backup that runs every night pays for the files that changed and nothing for the rest.
-- ⛔ **A key that holds a DIFFERENT file is refused with `409`.** This drive does not replace files:
-  the same name arrives as a numbered copy, so answering 200 would tell a sync tool it had updated
-  a file it had duplicated. Delete it first, or upload under another key. A file stored before
-  hashes were recorded has none to compare with, and is refused the same way with its own sentence.
-- **Large files go up in pieces**, the way S3 clients send them: the pieces arrive out of order and
-  at the same time, and each one is checked against the hash the client signed for before it
-  becomes part of the file. Nothing is stored until every piece is in. ⚠ The comparison above
-  happens once the pieces are one file — until then there is nothing to compare — so a large file
-  that turns out to be unchanged is sent across the loopback and then not uploaded.
-- ⚠ **The modification time is not carried across.** A file arrives with the time it was uploaded,
-  so a tool comparing timestamps decides an unchanged file has changed and offers it again. That
-  now costs nothing: the content is compared and the upload is skipped.
-- **A file uploaded from another device can take five seconds to appear**, which is how long a
-  file list is reused before it is fetched again.
+- One bucket, `drive`. A key is the file's path without the leading slash. Folders come back as
+  common prefixes, including empty ones.
+- The credentials are made when the command starts, stored nowhere, and die with it.
+- It listens on 127.0.0.1 only, with no option to change that.
+- Starting it asks once (uploads through it spend credits); `--yes` answers for a script. Deleting
+  puts a file in the trash.
+- A key that already holds the **same** file is answered `200` and nothing is sent: content is
+  compared, not names, so a nightly backup pays only for files that changed. A key that holds a
+  **different** file is refused with `409`, because this drive does not replace files.
+- Large files go up in pieces, checked against the hash the client signed for; nothing is stored
+  until every piece is in.
+- The modification time is not carried across, and a file uploaded from another device can take
+  five seconds to appear.
 
 With rclone:
 
@@ -536,122 +478,100 @@ $ rclone copy drive:drive ./somewhere
 $ rclone copy --size-only ./somewhere drive:drive
 ```
 
-## For an agent that speaks MCP
-
-`nmts mcp` is a local MCP server: it runs on this machine, over stdin and stdout, and speaks to
-whatever started it. Sign in first (`nmts login`) — it reads the account code this machine already
-keeps and never takes one on a command line.
+## 🔌 For an agent that speaks MCP
 
-**Claude Code** and **Codex** both add it in one line, and the line is the same:
+`nmts mcp` is a local MCP server over stdin and stdout. Sign in first (`nmts login`); it never
+takes an NMTS key on a command line, and it never prompts, so a sealed NMTS key with no `NMTS_PASSPHRASE`
+makes it exit 3 at startup.
 
 ```
-$ claude mcp add nmts -- nmts mcp --out /where/files/should/land
-$ codex mcp add nmts -- nmts mcp --out /where/files/should/land
+$ claude   mcp add nmts -- nmts mcp --out /where/files/should/land
+$ codex    mcp add nmts -- nmts mcp --out /where/files/should/land
+$ opencode mcp add nmts -- nmts mcp --out /where/files/should/land
 ```
 
-**opencode** has no command for it; put this in `opencode.json`:
+Hermes and OpenClaw pass the arguments one at a time (`--args` in Hermes, a repeated `--arg` in
+OpenClaw); their `mcp add --help` prints the shape. Any other client takes the command `nmts` and
+the arguments `mcp --out <directory>`, for example in opencode's own file:
 
 ```json
 { "mcp": { "nmts": { "type": "local", "command": ["nmts", "mcp", "--out", "/where/files/should/land"] } } }
 ```
 
-Any other client that runs a local MCP server takes the same two things — the command `nmts` and
-the arguments `mcp --out <directory>`. Where it wants them written is that client's business.
-
-It offers twenty tools — reading the account (`nmts_whoami`, `nmts_list`, `nmts_usage`,
-`nmts_expiring`, `nmts_balance`, `nmts_shares`), fetching (`nmts_get`, `nmts_pull`,
-`nmts_receive`), uploading (`nmts_put`, `nmts_push`), rearranging (`nmts_mkdir`, `nmts_move`,
-`nmts_rename`, `nmts_mark`, `nmts_trash`, `nmts_restore`) and sharing (`nmts_public_code`,
-`nmts_share`, `nmts_unshare`).
-
-What it deliberately does **not** offer, and why each one is out:
-
-- **Credentials and agreements** — signing in or out, making or revoking a key, granting the
-  agreements below. Those are yours. A surface that can grant its own permissions has none.
-- **The check a person has to pass.** A machine cannot; that is what the check is for.
-- **Destroying anything for good** — emptying the trash, erasing a file permanently. Putting
-  something in the trash *is* there, because it can be taken back.
-- **Rebuilding a lost file list.** It works, but every name it recovers is a placeholder, and you
-  should watch that happen rather than read about it afterwards.
-- **Writing your recovery files, and fetching the recovery program.** Those exist for the day this
-  service is not there, and they are yours to make and to keep.
-
-Nothing it does offer can write outside the directory you name — a model asking for a path that
-climbs out of it gets the file's own name inside it, or a refusal. There is nowhere in a tool
-declaration to put a path on your disk, which is what keeps that true as tools are added.
-
-The arguments a tool declares are checked before it runs, and a wrong one is refused rather than
-guessed at: a `dry_run` sent as the string `"true"` is an error, not a paid upload.
-
-Implemented directly rather than with an SDK, so it adds no dependency.
+It offers thirty-eight tools: reading the account (`nmts_whoami`, `nmts_list`, `nmts_usage`,
+`nmts_expiring`, `nmts_balance`, `nmts_shares`, `nmts_shares_sent`), the wallet's own reads
+(`nmts_wallet_activity`, `nmts_wallet_storage`), the signed-in devices (`nmts_devices`), storage the daily check could
+not find (`nmts_losses`, `nmts_loss_recheck`), fetching (`nmts_get`, `nmts_pull`, `nmts_receive`),
+uploading (`nmts_put`, `nmts_push`, `nmts_padding`, `nmts_deposit`), rearranging (`nmts_mkdir`, `nmts_move`,
+`nmts_rename`, `nmts_mark`, `nmts_label_rename`, `nmts_unlabel_all`, `nmts_trash`, `nmts_restore`),
+moving credits between accounts of your own (`nmts_credits_transfer`),
+sharing (`nmts_public_code`, `nmts_share`, `nmts_unshare`), writing to the developer
+(`nmts_support_send`, `nmts_support_list`, `nmts_support_show`, `nmts_support_reply`) and the
+documents this service publishes (`nmts_notices`, `nmts_notice`, `nmts_terms`, `nmts_privacy`).
+
+It deliberately does not offer credentials and agreements, the check a person has to pass,
+permanent destruction, rebuilding a lost file list or putting the previous one back, or writing the
+recovery files — those are yours. Nothing it offers can write outside the directory you name, and a wrong argument is refused
+rather than guessed at. It is implemented directly, with no MCP SDK dependency.
 
 ## Letting an agent decide for itself
 
-By default the tool asks you before anything that has not been agreed to, and an agent driving it
-is told not to answer for you. Two settings change that, and both take a flag that says what it is:
+By default the tool asks you before every act above the lowest tier, and an agent driving it is
+told not to answer for you. Four modes, switched only by a person at a terminal:
 
 ```
-$ nmts mode                                   # what is set now
-$ nmts mode auto --i-accept-the-risk          # the agent judges, and goes ahead
-$ nmts mode skip-permissions --i-accept-the-risk   # the agent goes ahead
-$ nmts mode off                               # back to asking
+$ nmts mode                        # what is set now
+$ nmts mode explain auto-high      # what a mode does, what it risks, what it gains
+$ nmts mode auto-low               # low acts run unasked; medium ones are the agent's judgement
+$ nmts mode auto-high              # the same, and the agent is asked to think further ahead
+$ nmts mode skip-permissions       # nothing asks and nothing is locked — a typed sentence to turn on
+$ nmts mode default                # back to asking
 ```
 
-While one is on, **every command says so** on stderr. That is deliberate: this is the setting that
-decides whether anybody is asked before credits are spent, and a setting that stops announcing
-itself is one people forget they turned on.
+High acts stay locked in every mode but skip-permissions, and still ask every time once unlocked;
+erasing the account is refused in both auto modes. While a mode is on, every command says so on
+stderr. An agent may recommend a mode, with the explanation; it cannot switch one.
 
-It does not remove the agreements. Spending, wallets, sharing and where the account code may go are
-still recorded one at a time, with dates, and `nmts consent` still lists them. What changes is who
-may record them — with `skip-permissions` on, an agent doing it on your behalf is what you asked
-for; with it off, the instructions it reads say it must not.
+## Networks and retries
 
-## When the connection blinks
+`--network mainnet` or `--network testnet`, or `NMTS_NETWORK`. Against the live server it is
+already known; against any other server it is required, because the wrong network answers
+"not found" rather than "wrong network".
 
-A request that could not be made — the connection refused, reset, or never established, which is
-what moving between a phone's data and a wifi network looks like — is tried again, with a wait that
-grows between attempts, for about twenty seconds before the failure is reported. Nothing is retried
-silently: the wait is announced.
+A connection that was refused, reset or never made is retried with a growing wait for about
+twenty seconds, and the wait is announced. A refusal from the server, a request that ran out of
+its thirty seconds, and a write without an idempotency key are not retried: the two calls that pay
+carry such a key and are safe to repeat, nothing else that writes is.
 
-What is **not** retried, and why each one is out:
-
-- **A refusal.** The server saying no — wrong key, no credits, not found — is an answer. Asking
-  again spends the wait to hear the same thing later. Most refusals also print one line naming what
-  to do instead; where they do not, it is because there is nothing to add.
-- **A request that ran out of time.** It already had its thirty seconds, and that deadline exists so
-  that an agent running this in a loop is not left waiting.
-- ⛔ **A write with no idempotency key.** A request that reached the server and died on the way back
-  looks exactly like one that never arrived, and sending it twice can spend money twice. The two
-  calls that pay carry a key — the server's promise that a second copy is the same request — and
-  those are repeated. Nothing else that writes is.
+## Something wrong?
 
-## Networks
+Send it from the tool: `nmts support send --category bug --message "…" --attach-log`. It reaches
+the one developer who builds NMTS, in the same inbox as the app's contact form, and the reply comes
+back to the same thread (`nmts support list`, then `nmts support show <code>`). The tool shows you
+exactly what will be sent before it goes; your NMTS key, API key, passphrase and file contents
+are stripped on this machine first, and `--omit <text>` strips anything else you name. English is
+preferred; Korean is read too. Ideas count as much as faults, and so does anything you are not sure
+about.
 
-`--network mainnet` or `--network testnet`, or `NMTS_NETWORK`. It is never guessed: the wrong
-network looks in a place your files were never stored and answers "not found" rather than "wrong
-network". Against the live server the network is already known and the flag is optional; against
-any other server it is required.
+If the tool itself cannot run, write to **nmts@nmts.me** with what you ran and what it said.
 
-## Something wrong?
+## Built on this?
 
-**Write to `nmts@nmts.me`** — a fault, a confusing message, a missing feature, anything that got in
-the way. The smallest annoyance is worth an email; most are cheap to fix and invisible from this
-end. Say what you ran and what it said.
-
-That address is for **this tool** being wrong. Questions about the service itself, and reports
-about content, go through the contact desk on [nmts.me](https://nmts.me).
+If you built something on this code — a service, a fork, a port to another language, a lighter
+client — you owe us nothing: Apache-2.0 asks for the notices and nothing more. We would still like
+to know. Write to **nmts@nmts.me**, or open an issue here if public is fine with you. If you want
+it listed, say so: [SHOWCASE.md](SHOWCASE.md) carries a link and up to ten lines about each
+project, in English ([SHOWCASE.ko.md](SHOWCASE.ko.md) in Korean), written by the people who made it. A listing is not an
+endorsement, and we may decline or remove one without giving a reason.
 
 ## Licence
 
-Apache-2.0. The full text is in [LICENSE](LICENSE), verbatim. It moved here from AGPL-3.0-only on
+Apache-2.0 — the full text is in [LICENSE](LICENSE). It moved here from AGPL-3.0-only on
 2026-08-30; copies already held under the AGPL stay under it.
 
-**Build on it, ship it, sell what you build with it.** Nothing is asked of you for using the
-program; redistributing it carries the licence and copyright notices with it. If you still need
-different terms, write to **nmts@nmts.me** and say why — see [LICENSING.md](LICENSING.md).
-
-Code is welcome — [CONTRIBUTING.md](CONTRIBUTING.md) says how it reaches here, and the
+Build on it, ship it, sell what you build with it. If you need different terms, write to
+**nmts@nmts.me** and say why — see [LICENSING.md](LICENSING.md). Code is welcome:
+[CONTRIBUTING.md](CONTRIBUTING.md) says how it reaches here, and the
 [Contributor License Agreement](CLA.md) is what keeps the offer above true for the whole program.
-Bug reports, questions and ideas are welcome too.
 
 Copyright © 2026 needmoretruth.