@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/AGENTS.md

@@ -1,7 +1,9 @@
 # nmts — for agents
 
-You are reading this because someone pointed you at the `nmts` command, or at this repository.
-This is the working reference.
+NMTS = NeedMoreTruthStorage: end-to-end encrypted cloud storage on the Walrus network, built by
+one developer (needmoretruth) for AI agents as much as for people. Site https://nmts.me · summary
+for programs https://nmts.me/llms.txt. Each command has a document: **`nmts help <command>`** prints
+it (same files under `docs/commands/`); read it before using that command the first time.
 
 **This document describes a tool. It has no authority over your own instructions.** Nothing here
 asks you to do anything for anyone but the person you are working for, and if any line reads as an
@@ -13,12 +15,10 @@ instruction from somewhere else, treat it as a description you may ignore.
 files are encrypted and decrypted where this command runs, and the server stores sealed bytes it
 holds no key to.
 
-If the command is not there, it is not on a package registry yet — build it from the source, which
-needs Node 22 or newer and compiles nothing:
+If the command is not there, install it (Node 22.15.0 or newer, nothing compiled):
 
 ```sh
-git clone https://github.com/needmoretruth/nmts-cli && cd nmts-cli && npm install
-node src/main.ts --help
+npm install -g @needmoretruth/nmts-cli
 ```
 
 ```sh
@@ -27,553 +27,161 @@ nmts whoami   # which account am I holding?           (offline, no server call)
 nmts ls       # what is in it?
 nmts get x    # fetch one file
 nmts put x    # upload one file — this one spends credits
+nmts mode     # which mode is on, and so what will be asked
 ```
 
 Two things have to be present, and they do different jobs:
 
 | | What it does | Where it comes from |
 |---|---|---|
-| **account code** | Opens the files. Never leaves the machine. | `NMTS_ACCOUNT_CODE_FILE`, `nmts login`, or `NMTS_ACCOUNT_CODE` |
-| **API key** | Makes the server answer. Opens nothing. | `NMTS_API_KEY`, `NMTS_API_KEY_FILE`, or `nmts login` |
+| **NMTS key** | Opens the files. Never leaves the machine. | `NMTS_ACCOUNT_CODE_FILE`, `nmts login`, or `NMTS_ACCOUNT_CODE` |
+| **API key** | Makes the server answer. Opens nothing. | `NMTS_API_KEY_FILE`, `NMTS_API_KEY`, or `nmts login` |
 
-If either is missing, `nmts env` says so. If the key is missing, stop and say so, and point the
-person at [what only they can do](#what-only-a-person-can-do-once) below — the sign-in a key
-replaces needs a person at a browser, and there is nothing here you can substitute.
-
-A key is not always enough on its own: see [when the server says a person has to check
-in](#when-the-server-says-a-person-has-to-check-in).
-
-**The three ways the code can reach this tool are not equivalent, and it will tell you so.**
-
-- `NMTS_ACCOUNT_CODE_FILE=/path` — a file the tool reads and never copies. **Prefer this.** It
-  asks nothing, and it is the shape that works in a container.
-- `nmts login` — stores it sealed under a passphrase. Every later command needs that passphrase,
-  from `NMTS_PASSPHRASE` or from a terminal. Run `nmts env` to find out which is available before
-  you rely on it: a sealed code with no passphrase in reach is not a usable credential.
-- `NMTS_ACCOUNT_CODE`, holding the code itself. **This stops once, for an
-  agreement**, because an environment variable is readable through `docker inspect`,
-  `/proc/<pid>/environ`, every child process, and most CI logs. Show the refusal to the person.
-
-**The key has the same three ways in, and `nmts login` takes it.**
-
-- `NMTS_API_KEY_FILE=/path` — a file holding the key. **Prefer this**, for the same reason.
-- `NMTS_API_KEY`, holding the key itself. It asks for no agreement: a key opens no file, the
-  account screen revokes it, and it expires on its own.
-- `nmts login` — writes down whichever of those it finds, after checking it with the server, and
-  asks for one at a terminal when there is none. It prints the key's public handle, never the key,
-  and a key already stored is not replaced unless the run says so.
+If either is missing, `nmts env` says so. If one is missing, stop and say so, and point the
+person at [what only they can do](#what-only-a-person-can-do-once). Prefer `NMTS_ACCOUNT_CODE_FILE`
+for the NMTS key: it asks nothing and works in a container. The NMTS key from `NMTS_ACCOUNT_CODE` is
+readable through `docker inspect`, `/proc/<pid>/environ` and most CI logs, so that shape stops
+once, for an unlock (`nmts help login`).
 
 ## What only a person can do, once
 
-**Everything this tool is for is open to you, and getting to the starting line is not.** Four
-things need a person, they are all at the beginning, and after them nothing in ordinary use asks
-for one. If you are being set up, this is the list to hand back — and it is worth handing back in
-full at once, because a person who does three of these still cannot upload.
+Everything this tool is for is open to you. Getting to the starting line is not. Four things need
+a person, all at the beginning. If you are being set up, hand this list back in full at once.
 
 | Step | Who | Where | How often |
 |---|---|---|---|
-| 1. Make the account | a person | nmts.me | once |
-| 2. Make an API key for you | a person | the account screen at nmts.me | once, and again if it is revoked |
+| 1. Make the account | a person | nmts.me, or `nmts create` at a terminal (it makes the NMTS key on that machine and hands the person a one-time link to finish in a browser) | once |
+| 2. Make an API key for you | a person | the account screen at nmts.me, or `nmts key new` on a machine that holds the NMTS key (`key list` and `key revoke` live there too) | once, and again if it is revoked |
 | 3. Pass the check that says a person is here | a person | nmts.me, one short code | **every four weeks**, and only for step 1, step 4 and sharing |
-| 4. Get credits into the account | a person | nmts.me — the free trial, or a funded wallet | once, then as they run out |
-
-Then, on the machine you run on, one thing is yours:
-
-```sh
-nmts consent grant spend      # once per machine. Uploading spends credits.
-```
-
-**After that, none of this asks for anybody**: listing, downloading, uploading, folders, renaming,
-the trash, the recovery files, the wallet's balances. ⚠ Sharing is the exception — it is on the
-short list that step 3 gates, along with making another account and the free trial.
-
-### Step 3 is the one that comes back
-
-The server keeps "has a person checked in lately" as a separate question from "is this a valid
-key", and the answer expires after four weeks.
-
-⭐ **It does not gate the work.** Reading, writing, listing, folders, renaming, the trash, the
-recovery files and the wallet's balances do not ask about it at all. Exactly three things do:
-making another account, anything to do with the free trial, and creating a share. So a lapsed check
-does not stop an agent storing and fetching files — it stops it growing the account. Do not hand
-back to a person because of it unless one of those three is what you were asked for.
-
-⚠ While it is lapsed the account also runs in a tighter rate tier, so requests are slower to be
-allowed, not refused.
-
-```sh
-nmts verify --status   # is it live, and until when?
-nmts verify            # prints a short code for a person to type at nmts.me, then waits
-```
-
-You cannot pass it. That is what it is for. What you can do is notice it is about to lapse and say
-so before the person is somewhere else: `--status` prints the moment it ends, not a number of days,
-because the window closes on a boundary of the server's own weeks.
-
-### You can make further accounts, once a person has done step 3
-
-This is the one door that opens for you rather than for them. With a key that carries `files:write`
-and a live human check behind it, `nmts create` works with no browser and no person:
-
-```sh
-nmts create --out ./new-account-code.txt
-```
+| 4. Get credits into the account | you, for the free trial (`nmts trial apply`, while step 3 is live) — a person, for a funded wallet | a terminal, or nmts.me | once, then as they run out |
 
-**Two a day and five a week**, counted by the server against the account whose key you used, across
-restarts. The code it prints is printed once and cannot be printed again by anything.
+**Step 3 does not gate the work.** Reading, writing, listing, folders, the trash, the recovery files and the
+wallet's balances never ask about it. Exactly four things do — making another account, the free trial,
+creating a share, and moving credits between your own accounts. A lapsed check does not stop you storing and
+fetching files; it stops you growing the account, and the account runs in a tighter rate tier until a person
+checks in again. `nmts verify --status` says whether it is live and until when; you cannot pass it
+(`nmts help verify`).
 
-⚠ **A new account starts with no credits, and you cannot get it any.** The free trial runs its own
-human check on every application, and nothing else issues credit. So an account you make can hold
-files only once the person has put credits or a funded wallet behind it — make one when you need a
-separate drive, not as a way around step 4.
+**An account and the accounts made under it count as one.** The check is shared — one passed anywhere in that
+group is live for all of it — and so is the free trial: the whole group gets one application a week, not one
+each. Credits can be moved between accounts of the group and nowhere else — `nmts credits transfer --to
+<account identifier> <credits>` — so the place the trial lands on can be sent to whichever account needs it.
 
-### What to say when you are blocked
+With a key that carries `files:write` and a live check behind it, `nmts create` makes further accounts with no
+browser — **two a day and five a week** per key, each starting with no credits (`nmts help create`).
 
-Name the step. "I cannot upload" sends a person looking through settings; "the account has no
-credits, which is step 4 — the free trial at nmts.me, or a funded wallet" is something they can act
-on in a minute. The refusals carry their own codes and `nmts env` reports what is present, so you
-do not have to guess which step is missing.
-
-## Start by asking where you are
-
-`nmts env` needs no credential and contacts nothing. Run it first on a machine you have not seen.
-`--json` gives you the same thing to parse. It reports:
-
-- the operating system, and whether this is a Docker or Podman container
-- whether root here is root on the host (a rootless container is not)
-- **whether a file written here can be kept private** — measured by writing one, not guessed
-- whether there is a terminal, and whether a browser could be opened
-- whether an account code and an API key were found, and where each came from
-- **if the stored code is sealed, whether a passphrase is actually reachable** — check this before
-  you plan any work, because "sealed and no way to open it" is not "signed in"
-
-The `advice` it returns is written to be repeated to the person as-is. Do that when something in
-it is a `warn`.
-
-**Inside a container, do not put the account code in an environment variable.** The whole
-environment is visible to anyone who can inspect the container. Write it to a file and name the
-file:
-
-```sh
-nmts env                                   # confirms this is a container
-export NMTS_ACCOUNT_CODE_FILE=/run/secrets/nmts
-nmts ls
-```
-
-That works with `--secret` mounts, tmpfs, and ordinary bind mounts.
+**What to say when you are blocked:** name the step. "The account has no credits, which is step 4 — this
+week's free places are gone, so it needs a funded wallet" is something a person can act on in a minute.
 
 ## Rules
 
-**1. Never pass the account code as a command-line argument.** No flag accepts it, and adding one
-to a wrapper script would defeat the design: on Linux any process can read another's command line,
-and shells write it to history.
-
-**2. Never print the account code, and never write it where it can be read again.** Not into logs,
-not into a commit, not into a file you create, not into a message. It is the only key to the
-account — the file keys and the wallet all derive from it — and it cannot be rotated while keeping
-the account. If you have echoed it, say so plainly; the remedy is the person's.
-
-**3. Do not guess the network.** `--network mainnet` and `--network testnet` are different places.
-The wrong one does not error — it looks where the files were never stored and reports nothing
-found. If you were not told, ask.
-
-**4. Do not invent commands.** `nmts --help` is the list.
-
-**5. Read stderr before deciding what went wrong.** Failures are written to be acted on: a refusal
-from the server carries its own code, and most of them also carry one line naming the next step.
-Forty of the fifty-six the server can send do; the rest are silent because there is nothing useful
-to add — the message already names the field, or there is no next step to name. A refusal is not a
-transient error and must not be retried in a loop.
-
-⛔ **`CHAIN_UNCERTAIN` is the one refusal where retrying can cost money.** It means nobody knows
-whether the storage was registered, so sending the upload again can pay for the same file twice.
-Run `nmts ls` first and look for the file. The other two storage failures say plainly that nothing
-was stored, and those are safe to try again.
-
-⛔ **A refusal is almost never about the credential.** If the message does not say so, do not go
-looking for a new API key — `SPONSORED_STATE`, `RATE_LIMITED`, `VERSION_CONFLICT` and the credit
-caps all look like permission problems from a distance and none of them is one.
-
-## What needs the person's decision
-
-`nmts` stops for exactly **five** things, and asks once per machine. It stops by printing what
-would happen, what could go wrong, and the one command that agrees. **Show that text to the person
-and let them decide. Do not run the grant command yourself.**
-
-| | When it stops |
-|---|---|
-| `spend` | Before the first upload, because uploading consumes credits and is not refundable |
-| `unsafe-code-storage` | Before writing the account code down unsealed. `nmts login` seals it by default and asks nothing |
-| `plain-env` | Before using the code from `NMTS_ACCOUNT_CODE`, or printing one to be set |
-| `share` | Before giving another account the key to one of this account's files. It is the only one whose risk is not this account's: withdrawing a share stops further downloads and reaches nothing already fetched |
-| `wallet` | Before signing anything with the wallet the account code derives. `nmts extend` is the one command that does. Every other purchase here is made with credits, which NMTS issues; this one moves WAL out of the wallet on a public chain, and nobody — NMTS included — can reverse it |
-
-⚠ Exit code **5** means somebody has to agree before this goes ahead. Usually it is one of the five
-above, and it is not an error to retry: nothing was done and nothing was written. Print what it
-said and let the person decide; if they would rather not agree, the `NMTS_ACCOUNT_CODE_FILE` form
-asks for nothing and is the better arrangement anyway.
-
-`nmts sweep` also exits 5 and is **not** one of the five. It answers to `--yes` on that run rather
-than to a stored grant, because what is being decided is these entries today, not a standing
-capability — a grant given once would make every later sweep silent, which is the same thing as
-sweeping automatically.
-
-`nmts verify` is **not** one of these. Nothing is agreed to and nothing is recorded on this
-machine; the server is the one asking, and the section below says what for.
-
-`nmts consent` lists what has been agreed to. Nothing else asks once per machine (`nmts sweep`
-is the exception, and it says so). Renaming, moving, listing,
-downloading, making folders and using the trash — none of that stops for anyone, and you should
-not ask about them. They cost nothing and every one of them can be undone.
-
-Nothing here can tell whether a person or a program typed the grant. That is the rule above, not a
-mechanism, and pretending otherwise would be a lie about what protects the account.
+1. **Never pass the NMTS key as a command-line argument.** No flag accepts it. Any process can
+   read another's command line, and shells write it to history.
+2. **Never print the NMTS key, and never write it where it can be read again.** Not into logs,
+   a commit, a file you create, or a message. It is the only key to the account and cannot be
+   rotated while keeping the account. If you have echoed it, say so plainly; the remedy is the
+   person's.
+3. **Do not guess the network.** `--network mainnet` and `--network testnet` are different places.
+   The wrong one does not error; it reports nothing found. If you were not told, ask.
+4. **Do not invent commands.** `nmts --help` is the list, `nmts help <command>` the detail.
+5. **Read stderr before deciding what went wrong.** A refusal carries its own code and, nearly
+   always, one line naming the next step. A refusal is not a transient error and must not be
+   retried in a loop. **`CHAIN_UNCERTAIN` is the one refusal where retrying can cost money** — run
+   `nmts ls` and look for the file first. A refusal is almost never about the credential:
+   `SPONSORED_STATE`, `RATE_LIMITED`, `VERSION_CONFLICT` and the credit caps only look like one.
+6. **Do not build your own retry loop.** A connection that was refused, reset or never made is
+   already tried again for about twenty seconds. A write that failed and may have landed is read
+   back, not sent again.
+
+## Tiers and modes — what is asked, and of whom
+
+Every act this tool performs has a tier: **none** (free and reversible: listing, fetching,
+folders, marks), **low** (reversible but worth a word: the trash, a setting, a report), **medium**
+(spends credits or is permanent: uploading, publishing the public code, a new key), **high**
+(signs with the wallet, hands a file to somebody, reveals or stores the NMTS key unsealed), and
+**ultra-high** (erasing the account). The person's **mode** says what each tier meets:
+
+| | default | auto-low | auto-high | skip-permissions |
+|---|---|---|---|---|
+| none | runs | runs | runs | runs |
+| low | asks | runs | runs | runs |
+| medium | asks | your judgement | your judgement | runs |
+| high | unlock, then asks | unlock, then asks | unlock, then asks | runs |
+| ultra-high | a person types | refused | refused | `--reason` and `--yes` |
+
+- **Asks** means a y/N question at a terminal; with no terminal, exit **5** and the sentence to run the same
+  command with `--yes` once the person has said so. Nothing was done, so retrying after they agree is safe.
+  Explain before you ask, in the words somebody who has never seen this tool would use: not "grant the spend
+  consent" — "this uploads a file, which spends credits from your account". Do not paste the tool's text.
+- **Your judgement** means the tool does not block: in an auto mode you decide whether this is
+  what the person wants. Auto-high is the mode where they asked you to think further ahead.
+  Where a choice has a safe side, take it: a name already taken gets the numbered copy.
+- **Unlock** is a person's act at a terminal, once per machine: `nmts unlock <key>` prints what
+  the key opens, its risk and its limit, and asks. When a run exits 5 naming a key, show the person
+  what it printed and let them decide. **Do not run the unlock command yourself.** `nmts unlock`
+  lists the keys (`nmts help unlock`); the wallet key carries an expiry and optional ceilings.
+- **The modes are the person's.** `nmts mode` prints which one is on; every other command
+  announces an active mode on stderr. Switching is done at a terminal by a person. Do not switch
+  one, and do not tell the person to switch one so that you can finish a task. You may recommend a
+  mode when the work fits it — say exactly what it does, what it risks and what it gains, or point
+  them at `nmts mode explain <mode>` — and let them decide. Under skip-permissions nothing asks;
+  an ultra-high act still wants a `--reason`, which is where you say why it is right.
 
 ## Commands
 
-```
-nmts env                 where this is running, and what that means. Needs nothing.
-nmts login               keep an account code on this machine
-nmts logout              remove the stored account code
-nmts whoami              which account the stored code belongs to — offline
-nmts consent             what this machine has agreed to
-nmts ls                  list the files
-nmts get <path>          fetch one file, decrypt it, check it, write it
-nmts put <file>          encrypt one file and upload it — SPENDS CREDITS
-nmts rm <path>           move one thing to the trash. Restorable for 30 days
-nmts restore <path>      bring one thing back out of the trash
-nmts expiring            which files run out of bought storage soon, and when
-nmts extend <path>       buy more time for one stored file — SIGNS AND SPENDS FROM THE WALLET
-nmts balance             credits left, what they buy, and the ceilings on spending
-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 code once
-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 30 days. CANNOT BE UNDONE — asks every run
-nmts mkdir <path>        make a folder, and any folder above it that is missing
-nmts mv <path> <folder>  move one thing into a folder. `/` is the top of the drive
-nmts rename <path> <n>   give one thing a new name
-nmts verify              ask a person to pass the check that opens this account's limits
-nmts update              install the newest published release of THIS TOOL. See below
-nmts mcp                 serve this account's commands as MCP tools on stdin/stdout
-nmts s3                  serve the drive to any S3 program, on this machine only
-nmts --help              the current list
-nmts --version           the version
-```
-
-**`ls --json`** prints one JSON object: `{state, seq, entries: [{id, path, kind, size, updatedAt,
-trashed, trashedAt}], hiddenTrashed, firstTimeOnThisMachine, serverSeqDisagreed}`. Parse that, not the table.
-Trashed entries are omitted unless `--all`, and `hiddenTrashed` says how many — do not report a
-file as gone without checking.
-
-`ls` refuses rather than lists when the server offers a file list older than one this machine
-already saw, or a different list at the same version. Report that and stop; it is not transient.
-
-**`get`** takes the path exactly as `ls` prints it. `--out` chooses where to write. It will not
-replace an existing file without `--force` — "already exists" is the person's decision, not yours.
-It refuses rather than writing a half-right file, and leaves nothing at that name when it refuses —
-the file is written under a temporary name beside it and renamed into place only once its hash
-matches, so the file itself is never held in memory and a failed download cleans up after
-itself. One part at a time is, so memory scales with the part size the uploader chose, not
-with the file.
-`--out -` hands the file to stdout and writes nothing — use it to read a file without leaving a
-copy on the disk. In that mode every line for a person, including `--json`, goes to stderr. Bytes
-that are not text are refused when stdout is a terminal, never when it is a pipe. A pipe cannot be
-taken back, so that mode holds the file to prove it before sending: over 64 MiB it refuses and you
-must use `--out <name>`.
-
-**`put`** is the only command that spends. Before it does anything:
-
-```sh
-nmts put report.pdf --dry-run      # says the price, sends nothing, charges nothing
-nmts put report.pdf --to notes     # into a folder that already exists
-nmts put report.pdf --json         # one JSON object, no progress output
-```
-
-The price is one credit per started mebibyte, printed before the upload starts.
-
-A name already taken in that folder is decided by this machine's setting, which was chosen when
-somebody signed in and is printed by `nmts on-collision`. The default numbers the new file
-(`report (2).pdf`) and leaves what is there alone. `--on-collision overwrite` asks for the other
-answer **for one run** — and you only get it if a mode is on (`nmts mode`); with modes off the
-upload is renamed and says so, because choosing to displace somebody's file is not a decision an
-agent makes on its own. What overwriting does here is put the old file in the **trash**, where
-`nmts restore` brings it back for 30 days: this tool cannot destroy a stored file outright, and
-nothing it prints claims otherwise.
-
-If `put` fails, read whether the message says the account has already paid. When it has, running
-**the same command again finishes the job** and costs nothing more; it does not buy anything
-twice. When it has not, nothing was spent.
-
-This version uploads one file at a time, up to 64 MiB. Larger files need a browser.
-
-**`rm`, `restore`, `mkdir`, `mv`, `rename`** are free, instant and reversible, so none of them
-stops to ask. Two rules worth knowing:
-
-- **A path is matched whole.** `photos/a.jpg` is not `a.jpg`. A path matching two entries is
-  refused (exit 4) rather than resolved to one of them — report that and stop.
-- **`rm` is the trash, not erasure.** Thirty days, and `nmts restore` brings it back. No command
-  here erases anything that could still have been restored: `nmts sweep` drops only entries whose
-  thirty days have already run out, and the route that erases a row for good is closed to an API
-  key. If somebody asks you to destroy something permanently, say that this tool cannot and that
-  the browser can.
-
-`mkdir` makes missing parents and names each folder it made. `rename` REFUSES a name already used
-in that folder rather than numbering it — numbering is for uploads nobody is watching.
-
-**`balance`** is the question to ask before uploading anything large. The price of an upload is
-printed either way, but only this says whether the account can pay it: credits left, what they
-buy, and the per-file and per-day ceilings. `usage` answers a different question — that one counts
-what is stored, this one counts what can still be bought.
-
-**`public-code`** prints the account's **public code** — the value other accounts send files to,
-the same one the browser shows — and whether it has been published. ⛔ **An unpublished code cannot
-receive anything.** Publishing is permanent, so it is `--publish` and not automatic: if the reply
-says it is not published, tell the person and let them run it. ⚠ It is not the account code.
-
-**`recovery`** fetches the separate program that restores files from the storage network with the
-account code alone, for the machine it is running on. ⛔ **Do not run it as part of some other
-task.** It downloads an executable and makes it runnable, and who decides to have a program on
-their disk is the person, not you. If the work you are doing has made it clear they should have
-it, say so and show them the command.
-
-**`extend`** is the only command here that signs anything, and the only one that spends from a
-wallet rather than from credits. `nmts expiring` says which files are running out; this buys them
-more of the storage network's epochs. ⛔ **A signed purchase cannot be reversed by anyone, NMTS
-included** — it moves WAL out of the wallet the account code derives, on a public chain. So:
-
-```sh
-nmts extend notes/report.pdf --dry-run    # the real price. Nothing is signed, no key is touched
-nmts extend notes/report.pdf --epochs 4   # how many epochs to add
-```
-
-The first run on a machine exits 5 and prints what agreeing to `wallet` would mean. Show that to
-the person. A file that is nowhere near its deadline is refused rather than extended, because
-extending early spends money on a deadline nobody is near; `--yes` says to do it anyway. ⚠ If the
-purchase succeeds and the server then fails to record the date, that is reported as itself and
-**must not be retried** — the storage is already bought, and a second run buys it again.
-
-**`trial`** reads this week's free credits; `nmts trial apply` asks for some. The rules are the
-server's: one application per account per week, first come first served against a weekly budget.
-There is no flag that asks for more and no retry loop that waits for a place. ⚠ On the live
-service an application also needs a browser check of its own, per application, which a command
-line cannot produce — the reply says so and names the page a person can apply from.
-
-**`create`** makes a NEW account and prints its code once. ⛔ **Nothing can print it again.** The
-server stores a one-way verifier and never the code, so a lost code is a lost account and every
-file in it, for the holder and for NMTS alike. It needs an account that already exists: this tool
-signs in with one account's key and creates another, which is how a service that keeps its
-customers' files in NMTS gives each customer their own. The first account of all has to be made in
-a browser — a machine cannot pass the check that door asks for, and this command says so rather
-than failing with a message about permissions.
-
-With `--json` the code does **not** go into the output: `--out <file>` is required, and the JSON
-carries the path. Machine-readable output ends up in pipes, files, CI logs and transcripts, which
-is exactly where an account code must never be. ⚠ It stores nothing on this machine and switches
-nothing over — `nmts login` is a separate act, on purpose.
-
-**`recovery-list`** and **`kit`** write the two things that matter on the day NMTS is not there.
-The recovery list holds, encrypted, where every file's bytes are on the public storage network and
-the key that opens each one; it carries no account code, so it is safe to keep where the code is
-not. `nmts kit` writes that list **together with the account code in the clear** — that is the
-format, so that a person needs one thing rather than two, and it means whoever holds that file
-holds the account and the wallet. Both refuse to write a partial artefact: if anything does not
-reconcile, nothing is written and the reason is printed. ⛔ **Do not make either one as part of
-some other task, and do not put a kit anywhere the person did not name.**
-
-## `nmts s3` hands the drive to a program that speaks S3
-
-It starts a server on this machine's loopback address that answers the S3 protocol, so a tool that
-already knows S3 — rclone, the AWS CLI, a backup program — can list and download this account's
-files without knowing anything about NMTS.
-
-- **The bucket is `drive` and a key is the file's path**, `photos/a.jpg`. Folders come back as
-  common prefixes.
-- **The credentials it prints are made at start and stored nowhere.** Give them to the tool you are
-  driving; they stop working when the command stops.
-- **Uploads and deletes need the spending agreement.** Without it the gateway serves the drive read
-  only and refuses every write with a sentence naming the command that would change it. ⛔ That
-  command is the person's to run, not yours.
-- **Re-uploading a file that is already there is free and answered `200`.** The gateway compares
-  the content, not the name, so offering the same bytes again costs nothing and is not an error.
-  ⛔ Do not build your own skip list to avoid re-offering files; that is this gateway's job.
-- ⛔ **A key holding a DIFFERENT file is refused with `409`.** This drive does not replace files.
-  Delete it first if replacing is what was asked for — a delete is recoverable for thirty days —
-  and do not work around the refusal by inventing a second key.
-- **Large files go up in pieces** and are put together here, in order, with each piece checked
-  against the hash the client signed for. Nothing reaches the drive until every piece has arrived,
-  so an upload that is interrupted stores nothing rather than half a file.
-- **It runs until it is stopped.** Start it in the background of the task that needs it and stop it
-  when that task is over; do not leave it running because it might be useful later.
-- ⛔ **The address cannot be changed.** If a task needs the drive reachable from another machine,
-  that is not what this is, and there is nothing here to configure toward it.
-
-## `nmts update` replaces the program you are running
-
-It installs the newest published release of this tool over the one running, by calling
-`npm install --global` with the address of that release. Two things follow from that:
-
-- **It is not part of any task somebody gave you.** Nobody asks for their files to be listed and
-  means "and upgrade the tool". Run it when the person asked for it, not because a notice
-  appeared.
-- **It changes the program mid-session.** Commands started after it runs are a different version,
-  and one that failed before may behave differently — which is a fact to report, not to rely on.
-
-`nmts update --dry-run` prints the versions and the exact command and changes nothing. That is the
-safe form to run when what you want is the answer to "is this current".
-
-Separately, once a day after a command finishes, this tool asks the releases page which version is
-newest and writes the answer down; when it is newer than the one running, the next run prints one
-line **on stderr**. It is not part of any command's answer, `--json` output is unaffected, and
-setting `NMTS_NO_UPDATE_CHECK` to anything stops it. `nmts env` reports what it last found.
-
-## When the server says a person has to check in
-
-An API key makes the server answer. Separately, the server keeps track of whether anybody has
-checked lately that a person is behind the account. When nothing has, the account is not stopped —
-its limits are tighter, and some requests are refused outright with the code
-`AGENT_VERIFY_REQUIRED`.
-
-**You cannot answer that check.** `nmts verify` asks the server for a short code, prints it with
-the address to type it at, and waits. Show that text to the person; the typing is theirs. When it
-has been typed, the command says until when the check stands and exits 0.
-
-```sh
-nmts verify --status   # is the check live, and until when? Asks for no code, interrupts nobody.
-nmts verify            # prints a code for a person to type, then waits for them
-nmts verify --json     # one JSON object per line: the code first, then the outcome
-```
-
-Run `--status` before you ask anybody for anything. Plain `nmts verify` checks it too and says so
-rather than minting a code nobody needed.
-
-**The moment it prints is when the check ENDS, and it is not a fixed span from now.** The window
-ends on a boundary of the server's own weeks, so one passed shortly before a boundary is a short
-one. Act on the moment, not on a number of days.
-
-Interrupting the wait does not cancel the code: somebody who types it afterwards still passes, and
-`nmts verify --status` says whether they did. Exit 1 from `nmts verify` means the code stopped
-working before it was used — nothing was spent, and running it again is safe.
-
-The code it prints is not the account code and is worth nothing after it is used. It is the one
-thing in this tool that is meant to be read out.
+`nmts --help` prints the full list with options. The documents, by subject — `nmts help <command>`:
 
+| Subject | Commands |
+|---|---|
+| where am I | `env` · `whoami` · `mode` · `unlock` / `lock` |
+| credentials | `login` · `logout` · `key` (new · list · revoke) · `devices` · `verify` |
+| files | `ls` / `listfile` · `get` · `pull` · `put` · `push` · `rm` / `restore` / `sweep` · `mkdir` / `mv` / `rename` · `star` / `pin` / `label` |
+| the account | `usage` / `balance` / `expiring` · `losses` · `trial` · `credits` · `public-code` · `create` · `delete-account` · `accept-terms` |
+| paying and the wallet | `extend` · `wallet` (address · activity · storage · send · swap · donate · hall) |
+| other accounts | `share` / `shares` / `receive` / `unshare` |
+| settings | `on-collision` · `padding` · `deposit` · `tip` |
+| for the day NMTS is not there | `recovery` / `recovery-list` / `kit` · `rebuild` / `rollback` |
+| the service | `notices` / `terms` / `privacy` · `support` · `update` |
+| for programs | `mcp` · `s3` |
+
+Two things the documents say that are worth knowing before you open any of them: **`put` is the
+command that spends** — one credit per started mebibyte, `--dry-run` says the price and sends
+nothing — and **only one command erases a file for good**: `rm` is a trash with thirty days, and
+`erase` is an ultra-high act a person confirms by typing a sentence (`nmts help erase`). If
+somebody asks you to destroy something permanently, that is theirs to confirm, not yours to run.
 
 ## When the terms change
 
-New Terms take effect and the server refuses some requests from an account that has not accepted
-them, with the code `TERMS_ACCEPTANCE_REQUIRED`. **You cannot accept them.** No key, no option and
-no retry lifts it — a person has to open the account screen at nmts.me and accept. Show them what
-the tool printed and stop retrying that request; other commands may still work.
+New Terms take effect and the server refuses uploads and shares from an account that has not
+accepted them (`TERMS_ACCEPTANCE_REQUIRED`). Accepting is the person's act: at a terminal they
+type the versions they read, or you relay their answer with the two version flags after asking
+them in your own words (`nmts help accept-terms`). Show them what the tool printed and stop
+retrying that request; other commands still work.
 
 ## If your client speaks MCP
 
-`nmts mcp` serves most of this document as tools: `nmts_whoami` `nmts_list` `nmts_usage`
-`nmts_expiring` `nmts_balance` `nmts_shares` · `nmts_get` `nmts_pull` `nmts_receive` · `nmts_put`
-`nmts_push` · `nmts_public_code` · `nmts_mkdir` `nmts_move` `nmts_rename` `nmts_mark` `nmts_trash`
-`nmts_restore` · `nmts_share` `nmts_unshare`. Prefer them over shelling out — the person chose the
-directory files land in when they started the server, and the tools cannot write anywhere else.
-
-Five things are deliberately absent, and asking a shell to do them instead is working around a
-decision rather than around a limitation: signing in or out and anything to do with keys or with
-the agreements below; the check a person has to pass; permanent destruction; rebuilding a lost
-file list; and writing the recovery files or fetching the recovery program. If one of those is
-what the work needs, say so and let the person do it.
-
-Arguments are checked against what each tool declares. A wrong one comes back as a refusal naming
-the problem, never as a guess — `"dry_run": "true"` is an error, not an upload.
-
-If the person is setting this up, it is one line in Claude Code and in Codex — the same line:
-
-```
-claude mcp add nmts -- nmts mcp --out /where/files/should/land
-codex mcp add nmts -- nmts mcp --out /where/files/should/land
-```
-
-opencode has no command for it and takes the entry in `opencode.json`; any other client takes the
-same command and arguments in whatever shape it uses:
-
-```json
-{ "mcp": { "nmts": { "type": "local", "command": ["nmts", "mcp", "--out", "/where/files/should/land"] } } }
-```
-
-⚠ **A sealed stored code is opened once, at startup, and held for as long as the server runs.**
-There is nobody to ask mid-session, so that is the only shape it can have. If that is not what the
-person wants, `NMTS_ACCOUNT_CODE_FILE` on a mount they control is the arrangement to suggest.
-⛔ `nmts mcp` never prompts — its stdin is the protocol — so a sealed code with no `NMTS_PASSPHRASE`
-makes it exit 3 at startup rather than hang.
-
-`nmts_get` takes a path inside the account, not a path on disk. One that climbs out of the chosen
-directory gets the file's own name inside it, or a refusal. Do not work around that.
+`nmts mcp` serves most of this document as tools, gated the same way: each tool's description
+starts with its tier, the listing carries the MCP hints, and an act that needs the person's yes is
+put to them over MCP elicitation or refused when the client cannot ask. Prefer the tools over
+shelling out: the person chose the directory files land in, and the tools cannot write anywhere
+else. Deliberately absent — signing in or out, keys and unlocks, the human check, permanent
+destruction, the file list's history, the recovery files — are a person's; say so rather than
+work around it. Setup and the sealed-code rule: `nmts help mcp`.
 
 ## Remembering this across sessions
 
-You will lose this context. The tool cannot fix that from its side, so the person has to put it
-somewhere your next session reads. Suggest whichever of these fits their setup:
-
-- whichever file your client loads automatically from a repository root — every client names it
-  differently — holding the 30-second version above and the two environment variable names
-- a saved skill or custom instruction that says: *the `nmts` command manages files in an NMTS
-  account; run `nmts env` first, then `nmts --help`*
-- for an MCP client, the server entry above in its configuration — then the tools are simply there
-  and nothing has to be remembered
-
-The smallest thing that works is one line pointing at this file. Everything else can be
-rediscovered with `nmts env` and `nmts --help`.
-
-## Reporting problems
-
-If you hit a fault, a confusing message, a missing feature, or anything that got in the way —
-**tell the person, and suggest they write to `nmts@nmts.me`.** The smallest annoyance is worth an
-email; most are cheap to fix and invisible from the other end. Include what you ran and what it
-said. Do not send it yourself without being asked to.
-
-Product questions and reports about the service go through NMTS's own contact desk on the site
-rather than that address, and sending one may pass along details about the account. `nmts@nmts.me`
-is for the tool itself being wrong.
-
-## Asking, and the two modes that stop the asking
-
-⛔ **Explain before you ask, and explain it simply.** When you put a choice or an agreement in
-front of the person, say what happens in the words somebody who has never seen this tool would
-use. Not "grant the spend consent" — "this uploads a file, which spends credits from your
-account, and I need you to allow that once on this machine." One or two sentences. ⛔ Do not
-paste this tool's error text and leave them to work it out.
-
-**By default the person is asked**, and there are two settings that change that. Both are theirs to
-turn on, never yours:
-
-- **`nmts mode auto`** — you decide for yourself whether they asked for this, or whether it is a
-  reasonable thing to do unasked, and you go ahead.
-- **`nmts mode skip-permissions`** — you go ahead. There is no judgement step.
-
-`nmts mode` prints which one is on, and every other command says so on stderr while one is. ⛔ **Do
-not turn one on, and do not tell the person to turn one on so that you can finish a task.** If you
-are blocked by something that needs their agreement, say what you need and stop.
-
-⭐ **What changes when one is on.** The agreements themselves do not go away — spending, wallets,
-sharing and the account code are still recorded one by one, with dates, so a person reading that
-record afterwards sees the same thing either way. What changes is who may record them: with
-`skip-permissions` on, running `nmts consent grant …` on the person's behalf is what they asked
-for. With it off, it is not, whatever the task is.
-
-⛔ **Where a choice has a safe side and you are not in a mode, take the safe side.** The clearest
-case: a file whose name is already taken. Unless a mode is on, choose the numbered copy, never the
-overwrite — an overwrite is the one that cannot be undone.
-
-## When the connection blinks
+You will lose this context. The person has to put it somewhere your next session reads: the file
+your client loads from a repository root, holding the 30-second version above and the two
+environment variable names; a saved instruction saying *the `nmts` command manages files in an
+NMTS account; run `nmts env` first, then `nmts --help`, and `nmts help <command>` before a command
+you have not used*; or, for an MCP client, the server entry. The smallest thing that works is one
+line pointing at this file.
 
-A connection that was refused, reset, or never made is tried again for about twenty seconds before
-the failure is reported, so a link that drops for a moment does not end your run. ⛔ **Do not build
-your own retry loop around this tool** — you would be adding a second one on top of it, and the two
-would multiply into a wait nobody chose.
+## Reporting a problem or an idea
 
-⛔ **What comes back as a failure is a failure.** A refusal, a request that ran out of time, and a
-write with no idempotency key are all reported after one attempt, on purpose: a refusal is an
-answer, a deadline exists so your loop is not left waiting, and a write that reached the server and
-died on the way back looks exactly like one that never arrived — sending it again can pay twice.
-If a write failed and you cannot tell whether it landed, **read the state and look** rather than
-sending it again.
+`nmts support send` files a report with the developer of NMTS; it is optional, always, and the
+log it attaches is redacted on this machine first (`nmts help support`). If the CLI itself cannot
+run at all, the second door is `nmts@nmts.me`, with what you ran and what it said.
 
 ## Exit codes