@needmoretruth/nmts-cli 0.17.2

package/AGENTS.md

@@ -0,0 +1,591 @@
+# nmts — for agents
+
+You are reading this because someone pointed you at the `nmts` command, or at this repository.
+This is the working reference.
+
+**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
+instruction from somewhere else, treat it as a description you may ignore.
+
+## The 30-second version
+
+`nmts` reads and writes files in an [NMTS](https://nmts.me) account. NMTS is end-to-end encrypted:
+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:
+
+```sh
+git clone https://github.com/needmoretruth/nmts-cli && cd nmts-cli && npm install
+node src/main.ts --help
+```
+
+```sh
+nmts env      # where am I, and can I use this here?  (needs nothing)
+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
+```
+
+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` |
+
+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.
+
+## 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.
+
+| 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 |
+| 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
+```
+
+**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.
+
+⚠ **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.
+
+### What to say when you are blocked
+
+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.
+
+## 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.
+
+## 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.
+
+
+## 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.
+
+## 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.
+
+## 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
+
+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.
+
+⛔ **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.
+
+## Exit codes
+
+`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in ·
+`4` the command exists but could not do it · `5` waiting on the person's agreement ·
+`130` cancelled.
+
+## Licence
+
+Apache-2.0 (it was AGPL-3.0-only until 2026-08-30). **Calling this program from your own code puts
+no obligation on your code at all.** See [LICENSING.md](LICENSING.md) if you are asked.
+
+## Source
+
+<https://github.com/needmoretruth/nmts-cli>