@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/zstd-node.js

@@ -0,0 +1,71 @@
+// The zstd encoder this program hands to the file-list codec (NCF-3 §6.3.4, compression flag 0x02).
+//
+// ⛔ NOTHING IS IMPLEMENTED HERE. The shared codec declares the SHAPE of an encoder and a register
+//    to put one in; the browser fills that register with a WebAssembly build it fetches, and this
+//    file fills it with Node's own `zlib`. Writing a compressor by hand would be a second answer
+//    to a solved problem, and the two halves of the product have to produce the same bytes.
+//
+// ⛔ THE FRAME IS BOUNDED BEFORE ANYTHING IS ALLOCATED FOR IT, twice. A zstd frame says up front
+//    how many bytes it expands to; that number is read out of the header (14 bytes, no allocation)
+//    and compared against the caller's bound, and the bound is then ALSO handed to `zlib` as
+//    `maxOutputLength`, which refuses rather than truncating. A file list is authenticated, so a
+//    frame this big cannot arrive from a stranger — but a build that met a corrupt one must not be
+//    asked for a gigabyte of memory first, and a decompressor that quietly returned a SHORTER list
+//    would be the one failure this format may never have.
+//
+// ⛔ `node:zlib` IS IMPORTED ONLY WHEN A LIST IS ACTUALLY READ OR WRITTEN. An agent runs this tool
+//    in a loop, so everything loaded before the command is known is paid for thousands of times.
+//    The module body below holds two closures and nothing else.
+//
+// ⚠ NODE 22.15.0 IS THE FLOOR. zstd landed in Node's `zlib` there (and in 23.8.0 on the odd-numbered
+//   line); `package.json` states it, and a build without it simply registers nothing — the writer
+//   falls back to gzip, which every reader of both format versions understands.
+import { setZstdCodec, zstdContentSize } from "./shared/lib/drive/zstd.js";
+let loaded = null;
+async function zlib() {
+    if (loaded === null)
+        loaded = await import("node:zlib");
+    return loaded;
+}
+const codec = {
+    async compress(bytes, level) {
+        const z = await zlib();
+        return z.zstdCompressSync(bytes, {
+            params: { [z.constants.ZSTD_c_compressionLevel]: level },
+        });
+    },
+    async decompress(bytes, maxOut) {
+        // Read the frame's own claim first. The codec above this one checks it too; this is the last
+        // place before a buffer is sized from a number the frame supplied about itself.
+        const declared = zstdContentSize(bytes);
+        if (declared === null) {
+            throw new Error("This part of the file list does not say how large it expands to.");
+        }
+        if (declared > maxOut) {
+            throw new Error(`This part of the file list claims ${declared} bytes, over the ${maxOut} allowed.`);
+        }
+        const z = await zlib();
+        return z.zstdDecompressSync(bytes, { maxOutputLength: maxOut });
+    },
+};
+/** True once this process has handed the codec over, so the register is written once. */
+let registered = false;
+/**
+ * Make this program able to write and read compression flag 0x02. Safe to call more than once.
+ *
+ * ⛔ CALLED FROM THE FILE-LIST FLOW RATHER THAN FROM THE ENTRY POINT, and that is deliberate: the
+ *    package is a library and an MCP server as well as a command, and a list opened through any of
+ *    those doors has to be able to expand a zstd frame the browser wrote. Putting it here also
+ *    means `nmts --help` never loads it.
+ */
+export function registerNodeZstd() {
+    if (registered)
+        return;
+    registered = true;
+    setZstdCodec(codec);
+}
+/** For tests that need this process to look like a build with no encoder. */
+export function forgetNodeZstd() {
+    registered = false;
+    setZstdCodec(null);
+}

package/docs/commands/accept-terms.md

@@ -0,0 +1,15 @@
+# nmts accept-terms — accept a new version of the Terms
+
+Commands: accept-terms
+Tiers: accept-terms=none · accept-terms.accept=high
+
+When new Terms take effect, the server refuses uploads and shares from an account that has not
+accepted them (`TERMS_ACCEPTANCE_REQUIRED`). `accept-terms --status` says where the account
+stands and reads nothing else.
+
+Accepting is the person's act. At a terminal they read the documents (`nmts terms`, `nmts privacy`,
+`nmts notices` for what changed) and type the two versions. When you are relaying their answer,
+put the question to them in your own words, then run
+`nmts accept-terms --accept-terms <version> --accept-privacy <version> --yes` — the versions they
+named, never "the current one". It needs the NMTS key, is asked about in every mode but
+skip-permissions, and has no lock. The other way in is the account screen at nmts.me.

package/docs/commands/create.md

@@ -0,0 +1,17 @@
+# nmts create — make a new account
+
+Commands: create
+Tiers: create=high
+
+Signs in with one account's key and creates another, printing the new code once — nothing can
+print it again, because the server stores a one-way verifier and never the NMTS key. This is how a
+service that keeps its customers' files in NMTS gives each customer a drive; the first account of
+all has to be made in a browser. It needs a key with `files:write` and a live human check behind
+it, and the server allows two a day and five a week per key.
+
+There is no lock: the account does not exist yet. The person's acceptance is the two flags,
+`--accept-terms <version> --accept-privacy <version>` — a version they read, never "the current
+one" — and without them it is refused. With `--json` the NMTS key does not go into the output:
+`--out <file>` is required and the JSON carries the path. A new account starts with no credits,
+and the free trial runs its own human check on every application. It stores nothing on this
+machine and switches nothing over.

package/docs/commands/credits.md

@@ -0,0 +1,34 @@
+# nmts credits — moving credits between your own accounts
+
+Commands: credits
+Tiers: credits=none · credits.transfer=medium
+
+`nmts credits transfer --to <account identifier> <credits>` moves whole credits from the account
+this key belongs to onto another account of the same family — the account a person made, and every
+account made under it. `--to` takes the receiving account's identifier: what `nmts whoami` prints
+for that account, and what the account screen lists beside an AI account. `--json` prints
+`{"to":"…","credits":5,"from_balance":80,"to_balance":50}`; without it, both balances are printed
+under the line that says how many moved.
+
+**It cannot reach anyone else.** A recipient outside the family is refused, and an account that
+does not exist is refused in exactly the same words — so this door cannot be used to find out which
+identifiers are real. There is no price, no fee and no third party here: nothing is bought or sold,
+and the family's total is what it was a moment before.
+
+**Why it exists.** The free trial, the human check and the ceilings belong to the whole family: one
+week's place for the tree rather than one each. That place lands on one account, and this is how it
+reaches the account that needs it.
+
+It needs the account's human check to be live, the same as the free trial does. When it is not, the
+refusal names `nmts verify` — the code a person types at a browser — rather than a credential
+problem. It is a **medium** act: asked in the default mode, your judgement in an auto mode. Nothing
+is spent by moving credits, and running the same command the other way puts them back.
+
+The credits keep the expiry they already had. The move drains the soonest-expiring lots first, so
+sending 100 may arrive as several grants with different dates, and moving them never renews them.
+
+Four refusals, four different remedies, and none of them is a retry:
+`CREDIT_TRANSFER_OUTSIDE_FAMILY` (name an account of your own) · `CREDIT_TRANSFER_SELF` (that is
+the account sending) · `CREDIT_TRANSFER_INSUFFICIENT` (send less — the refusal carries what was
+needed and what the account can spend) · `CREDIT_TRANSFER_ZERO` (send some). Nothing is moved and
+nothing is held in any of the four.

package/docs/commands/delete-account.md

@@ -0,0 +1,14 @@
+# nmts delete-account — erase the account's server record
+
+Commands: delete-account
+Tiers: delete-account=ultra-high
+
+Erases the account, the file list, every file's record and share, sessions and keys. It cannot be
+undone. Not erased: the bytes on the storage network (paid through their term, unreadable without
+the records) and the NMTS key on this machine (`nmts logout` removes it). Storage already paid
+for is not refunded — the funds went to the network, never to NMTS.
+
+It is the one act above high. In the default mode a person types a sentence at the terminal; in
+both auto modes it is refused whatever is unlocked; under skip-permissions it runs only with
+`--reason "<why>"` and `--yes`, and the reason is the place to say, having thought it through,
+why this is what the person wants. Do not run it because it would tidy something up.

package/docs/commands/deposit.md

@@ -0,0 +1,27 @@
+# nmts deposit — the credit deposit an upload sets aside
+
+Commands: deposit
+Tiers: deposit=none · deposit.set=low
+
+Every file paid for with credits sets a deposit aside in the same transaction as the price: whole
+credits, from 0 to 64, chosen per upload. The deposit is what a later chain operation on that file
+is charged against — releasing its storage early, or a storage operation that costs the network a
+fee — converted to credits, at least one per operation, and whatever is left comes back when the
+storage period ends. It does not count against the per-file or per-day ceilings, and it returns
+with the price if the chain never registers the upload.
+
+`nmts deposit` prints what this account sets aside by default, `64 (not set)` until somebody
+chooses; `nmts deposit <n>` records another number. `put --deposit <n>` and `push --deposit <n>`
+set it for one run without changing the default, and are refused before anything is sent when the
+number is not a whole 0 to 64. A wallet-paid upload takes no deposit and refuses the flag: the
+wallet buys its own storage.
+
+`0` is a real answer and is not withheld. A file with no deposit still releases — it pays twice
+the same chain fee out of the balance at that moment, and is refused, with both numbers named,
+when the balance cannot cover it. Every screen that offers 0 says that in the same breath.
+
+The default lives in the sealed file list, so the server never learns it and it follows the account
+to every device; reading it costs a list read and setting it costs a list write, which is why
+setting it is a low act (asked once in the default mode, run in an auto mode). It applies to what
+is uploaded next: a deposit already set aside on a stored file is that file's and is not moved.
+`nmts balance` shows what is held, what each file set aside and how much of it has been spent.

package/docs/commands/devices.md

@@ -0,0 +1,9 @@
+# nmts devices — what is signed in to this account
+
+Commands: devices
+Tiers: devices=none · devices.sign-out=high(sign-out)
+
+Lists the devices and keys signed in to this account. `--sign-out <id|all>` ends one or all of
+them; whoever is there is signed out at once. It needs the NMTS key beside the API key, is locked
+until a person runs `nmts unlock sign-out`, and asks on every run in every mode but
+skip-permissions — at the terminal, or with `--yes` after the person has said so.

package/docs/commands/documents.md

@@ -0,0 +1,10 @@
+# nmts notices, terms, privacy — what NMTS has posted
+
+Commands: notices, terms, privacy
+Tiers: notices=none · terms=none · privacy=none
+
+`notices` lists what NMTS has posted; `notices <id>` prints one and `--save <id>` keeps it as a
+file. `terms` prints the Terms of Service in force (`--board` for the message board's own,
+`--lang ko` for Korean), `privacy` the Privacy Policy; `--save` writes either under the name the
+server gives it, `--out` says where. Each document prints its version at the top — the value
+`accept-terms` asks for. All three only read.

package/docs/commands/env.md

@@ -0,0 +1,21 @@
+# nmts env — where this is running, and what that means
+
+Commands: env
+Tiers: env=none
+
+Needs no credential and contacts nothing. Run it first on a machine you have not seen; `--json`
+gives the same thing to parse. It reports the operating system; whether this is a Docker or Podman
+container and whether root here is root on the host; whether a file written here can be kept
+private (measured, not guessed); whether there is a terminal and whether a browser could be
+opened; whether an NMTS key and an API key were found and where each came from; if the stored
+code is sealed, whether a passphrase is actually reachable; which agent left a marker here; and
+what the version check last found. The `advice` it returns is written to be repeated to the person
+as-is — do that when something in it is a `warn`.
+
+Codex, Hermes and OpenClaw clear the environment before starting an MCP server, so none of
+`NMTS_ACCOUNT_CODE`, `NMTS_ACCOUNT_CODE_FILE`, `NMTS_API_KEY` or `NMTS_PASSPHRASE` survives there.
+Store the credentials with `nmts login` instead; an empty `agentHosts` list is what those three
+look like, not evidence that no agent is running.
+
+Inside a container, do not put the NMTS key in an environment variable. Write it to a file
+and set `NMTS_ACCOUNT_CODE_FILE` to its path — `--secret` mounts, tmpfs and bind mounts all work.

package/docs/commands/extend.md

@@ -0,0 +1,27 @@
+# nmts extend — buy more storage time for one file
+
+Commands: extend
+Tiers: extend=high(wallet)
+
+Signs and spends WAL from the wallet your NMTS key derives. It is a standing choice: locked
+until a person runs `nmts unlock wallet` at a terminal (scope `storage` is enough, with an expiry
+and, if they want one, a spending ceiling), and asked nothing afterwards while that unlock lasts.
+
+```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 (default 2)
+```
+
+If the account holds a standing share (`nmts tip`), that share of the WAL just paid goes to the
+developer right after the extension, without a question.
+
+```sh
+```
+
+Both forms print the price in WAL, the chain fee in SUI measured by a dry run of the exact
+transaction (`null` in `--json` when it could not be measured, never 0), and what the wallet
+holds. A wallet short of either exits 4 with the two numbers before anything else; a balance the
+chain could not read is said as unread, not as zero. A file nowhere near its deadline is refused
+rather than extended; `--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.

package/docs/commands/folders.md

@@ -0,0 +1,10 @@
+# nmts mkdir, mv, rename — folders and names
+
+Commands: mkdir, mv, rename
+Tiers: mkdir=none · mv=none · rename=none
+
+Free, instant, reversible, and none of them stops to ask. `mkdir <path>` makes a folder and any
+missing folder above it. `mv <paths> <folder>` moves things into a folder; `/` is the top of the
+drive. `rename <path> <name>` gives one thing a new name and refuses a name already used in that
+folder rather than numbering it. Paths are matched whole, and a path matching two entries is
+refused (exit 4).

package/docs/commands/get.md

@@ -0,0 +1,14 @@
+# nmts get — fetch one file
+
+Commands: get
+Tiers: get=none
+
+Takes the path exactly as `nmts ls` prints it, fetches the sealed parts, decrypts and checks them,
+and writes the file. `--out` chooses where. It will not replace an existing file without `--force`
+— "already exists" is the person's decision.
+
+It never leaves a half-right file: bytes go to a temporary name beside the target and are renamed
+into place only once the hash matches, one part held in memory at a time. `--out -` hands the file
+to stdout and writes nothing; in that mode every line for a person, including `--json`, goes to
+stderr, binary bytes are refused when stdout is a terminal, and files over 64 MiB are refused
+because a pipe cannot be taken back.

package/docs/commands/key.md

@@ -0,0 +1,14 @@
+# nmts key — API keys made from the NMTS key
+
+Commands: key
+Tiers: key=none · key.new=medium · key.list=none · key.revoke=medium
+
+`key new` makes an API key with the NMTS key alone — no browser — and stores it as this
+machine's credential; `--print` shows it once as well. `--scopes read,write,spend` says what it may
+do (default `read`; a program that uploads needs all three), `--days`/`--until` how long it lasts
+(the server clamps at its own ceiling and the reply says the date). `key list` shows every key of
+the account — what it may do, when it stops, when it was last used, and which one is this
+machine's. `key revoke <id>` ends one and `key revoke all` ends every one; whatever used it stops
+working. All three present the NMTS key's proof, never an API key: an API key cannot list or cut keys, and
+that is what makes revoking mean something. In the default mode `new` and `revoke` ask first (or
+take `--yes`); in an auto mode they are your judgement. NMTS keeps no copy of a key.

package/docs/commands/login.md

@@ -0,0 +1,23 @@
+# nmts login — keep the NMTS key on this machine, and take an API key
+
+Commands: login
+Tiers: login=none · login.plain=high(unsafe-code-storage) · login.env=high(plain-env)
+
+`nmts login` stores the NMTS key sealed under a passphrase, checks whichever API key it finds
+(`NMTS_API_KEY_FILE`, `NMTS_API_KEY`) with the server, and stores that too. It prints the key's
+public handle and never the key. It does not replace a stored key unless the run says so.
+
+Every later command needs the passphrase, from `NMTS_PASSPHRASE` or a terminal. A sealed code with
+no passphrase in reach is not a usable credential; `nmts env` says which case this machine is in.
+
+Two other shapes exist and both are locked until a person opens them once, at a terminal:
+
+- `--plain` stores the NMTS key unsealed. Unlock: `nmts unlock unsafe-code-storage`.
+- `--env` stores nothing and prints the variable to set. Unlock: `nmts unlock plain-env`. The same
+  unlock covers reading the NMTS key from `NMTS_ACCOUNT_CODE` on every command — an environment
+  variable is readable through `docker inspect`, `/proc/<pid>/environ` and most CI logs.
+
+Once unlocked, neither asks again: they are standing choices, not per-run questions.
+
+Prefer `NMTS_ACCOUNT_CODE_FILE=/path` over any of this: the file is read and never copied, it asks
+nothing, and it is the shape that works in a container. See `nmts help env`.

package/docs/commands/logout.md

@@ -0,0 +1,11 @@
+# nmts logout — remove the stored credentials
+
+Commands: logout
+Tiers: logout=none
+
+Removes the NMTS key and API key this tool stored on this machine. Nothing on the server
+changes: the key stays valid until revoked (`nmts key revoke`, or the account screen), and the
+account is untouched. A code that came from an environment variable or a file is not touched
+either — this only forgets what `nmts login` wrote.
+
+Run it when a machine is handed over or a task is finished on a machine the person does not keep.

package/docs/commands/losses.md

@@ -0,0 +1,13 @@
+# nmts losses — storage the daily check could not find
+
+Commands: losses
+Tiers: losses=none · losses.dismiss=medium
+
+Lists storage objects paid with this account's credits that NMTS's daily check could not find on
+the chain, newest first: a public chain object id and the day a check first missed it, no file
+name, because the server cannot pair them. `--recheck <id>` asks the chain again now. Both only
+read.
+
+`--dismiss <id>` puts a line down for good, which is somebody saying "I have read this". In the
+default mode it asks first (or takes `--yes`); in an auto mode it is your judgement, and the safe
+judgement is to show the person the line rather than dismiss it for them.

package/docs/commands/ls.md

@@ -0,0 +1,16 @@
+# nmts ls — list the files
+
+Commands: ls, listfile
+Tiers: ls=none · listfile=none
+
+`nmts ls` lists the account's files. `--json` prints one 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. `--find <text>`
+keeps only names containing the text, `--sort name|size|date` and `--desc` order the listing.
+
+It refuses rather than lists when the server offers a file list older than one this machine has
+already seen, or a different list at the same version. Report that and stop; it is not transient.
+
+`nmts listfile` writes this machine's copy of the sealed file list out as a file (`--out`, or
+`--out -` for stdout). It is sealed: without the NMTS key it says nothing.

package/docs/commands/marks.md

@@ -0,0 +1,9 @@
+# nmts star, pin, label — marks on files
+
+Commands: star, unstar, pin, unpin, label, unlabel
+Tiers: star=none · unstar=none · pin=none · unpin=none · label=none · unlabel=none
+
+Free and reversible; nothing here asks. `star <files>` gathers files in favourites, `pin <files>`
+holds them at the top of their folder, and `label <name> <files>` attaches a word you choose; the
+`un-` forms take each off. A label exists while a file wears it. `label --rename <old> <new>`
+renames a label on every file that carries it; `unlabel <name> --all` takes it off all of them.

package/docs/commands/mcp.md

@@ -0,0 +1,33 @@
+# nmts mcp — serve this account as MCP tools
+
+Commands: mcp
+Tiers: mcp=none
+
+Serves most of this tool's commands as MCP tools on stdin/stdout. The person chose the directory
+files land in when they started the server (`--out`), and no tool takes a destination. Each tool's
+description starts with its tier, the listing carries the MCP hints (read-only, destructive), and
+the same gate the command line runs sits before every call: a locked act is refused until a person
+unlocks it at a terminal, and an act that needs the person's yes in this mode is put to them over
+MCP elicitation — or refused, naming the way round it, when the client cannot ask.
+
+The tools: `nmts_whoami` `nmts_list` `nmts_usage` `nmts_expiring` `nmts_balance` `nmts_shares`
+`nmts_shares_sent` · `nmts_wallet_activity` `nmts_wallet_storage` · `nmts_devices` · `nmts_notices`
+`nmts_notice` `nmts_terms` `nmts_privacy` · `nmts_losses` `nmts_loss_recheck` · `nmts_get`
+`nmts_pull` `nmts_receive` · `nmts_put` `nmts_push` `nmts_padding` `nmts_deposit` · `nmts_public_code` ·
+`nmts_mkdir` `nmts_move` `nmts_rename` `nmts_mark` `nmts_label_rename` `nmts_unlabel_all`
+`nmts_trash` `nmts_restore` · `nmts_credits_transfer` · `nmts_share` `nmts_unshare` · `nmts_support_send`
+`nmts_support_list` `nmts_support_show` `nmts_support_reply`.
+
+Deliberately absent: signing in or out, keys and unlocks, the human check, permanent destruction,
+rebuilding or rolling back the file list, and the recovery files. If one of those is what the work
+needs, say so and let the person do it.
+
+```
+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
+```
+
+A sealed stored code is opened once, at startup; `nmts mcp` never prompts, so a sealed code with
+no `NMTS_PASSPHRASE` exits 3 at startup rather than hang. Arguments are checked against what each
+tool declares — `"dry_run": "true"` is a refusal, not an upload.

package/docs/commands/mode.md

@@ -0,0 +1,29 @@
+# nmts mode — how much an agent may decide without asking
+
+Commands: mode
+Tiers: mode=none
+
+Every act this tool performs has a tier — none, low, medium, high, ultra-high — and the 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: at a terminal, a y/N question; with no terminal, exit 5 and the sentence to run again
+with `--yes` after the person has said so. "Your judgement" means the tool does not block: in an
+auto mode you decide whether this is what the person wants, and auto-high is the mode where they
+asked you to think further ahead than auto-low. "Unlock" is `nmts unlock <key>`, a person's act at
+a terminal (`nmts help unlock`). Under skip-permissions nothing asks and nothing is locked; an
+ultra-high act still wants a `--reason`, which is where you say why it is right.
+
+Switching is a person's act: `nmts mode auto-low` at a terminal (the auto modes ask y/N, skip-
+permissions asks for a typed sentence); `nmts mode default` turns it off; `nmts mode explain
+<mode>` prints what a mode does, its risk and its gain, and `nmts mode` prints which one is on.
+Every other command announces an active mode on stderr. Do not switch a mode, and do not tell the
+person to switch one so that you can finish a task; you may recommend one when it fits, with the
+explanation, and let them decide.

package/docs/commands/on-collision.md

@@ -0,0 +1,13 @@
+# nmts on-collision — a name already in use
+
+Commands: on-collision
+Tiers: on-collision=none · on-collision.set=low
+
+Reads or sets what an upload does when its name is already taken in the destination folder:
+`rename` numbers the new file (`report (2).pdf`) and leaves what is there alone; `overwrite` puts
+the old file in the trash, where `nmts restore` brings it back for thirty days. The default is
+`rename`. Setting it is a low act: asked once in the default mode, run in an auto mode.
+
+`put --on-collision overwrite` asks for the other answer for one run, and only takes effect while a
+mode is on; in the default mode the upload is renamed and says so, because displacing somebody's
+file is not a decision an agent makes alone.

package/docs/commands/padding.md

@@ -0,0 +1,13 @@
+# nmts padding — how file sizes are hidden
+
+Commands: padding
+Tiers: padding=none · padding.set=low
+
+A stored file's size is public on the storage network no matter what; padding is how coarsely it
+is rounded up before sealing. `standard` allows a few dozen sizes per doubling for about one
+percent more storage; `pow2` allows one per doubling, hides more, and costs more on average; `off`
+rounds nothing, so the file's exact length is visible to the network and to anyone who reads the
+blob, and about one percent less storage is used. The setting lives in the sealed file list, so it
+follows the account to every device and the server never learns it. Reading costs a list read;
+setting costs a list write, is a low act (asked once in the default mode, run in an auto mode), and
+applies to what is uploaded next — bytes already on the network are not re-padded.

package/docs/commands/public-code.md

@@ -0,0 +1,9 @@
+# nmts public-code — the code other accounts send files to
+
+Commands: public-code
+Tiers: public-code=none · public-code.publish=medium
+
+Prints the account's public code and whether it has been published. It is not the NMTS key.
+An unpublished code cannot receive anything. Publishing is permanent, so it is `--publish` and not
+automatic: in the default mode it asks first (or takes `--yes`); in an auto mode it is your
+judgement, and a permanent, public act is one to put to the person.

package/docs/commands/pull.md

@@ -0,0 +1,9 @@
+# nmts pull — fetch a folder, or everything
+
+Commands: pull
+Tiers: pull=none
+
+Downloads a whole folder, or the whole account with no argument, keeping its shape under `--out`.
+Files already present with the right content are skipped; `--force` replaces what differs. Unlike
+`push`, it carries on past a file that fails and reports the list at the end, because a download
+that fails costs nothing to try again.

package/docs/commands/push.md

@@ -0,0 +1,12 @@
+# nmts push — upload a whole directory
+
+Commands: push
+Tiers: push=medium · push.wallet=high(wallet)
+
+Uploads a directory, rebuilding its shape in the account, and spends credits the way `put` does
+(`nmts help put`). It stops at the first failure, saying what is already uploaded; running it again
+sends only the rest. Names already in the destination are skipped, dot-files are left alone
+without `--hidden`, and symbolic links are not followed. `--to` names the destination folder,
+`--dry-run` prices the whole run and sends nothing.
+
+`--pay wallet` does what it does for `put`, one file at a time, under the same standing unlock.

package/docs/commands/put.md

@@ -0,0 +1,36 @@
+# nmts put — encrypt one file and upload it
+
+Commands: put
+Tiers: put=medium · put.wallet=high(wallet)
+
+This is the command that spends. The price is one credit per started mebibyte, printed before the
+upload starts. In the default mode it asks first (answer at the terminal, or run with `--yes`);
+in an auto mode it runs when you judge it is what the person wants.
+
+```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 --name x.pdf   # under another name
+nmts put report.pdf --json         # one JSON object, no progress output
+```
+
+A file larger than one part (64 MiB by default, `--part-size` changes it) is split and each part
+is bought separately; a run that stops partway is finished by running the same command again, which
+buys only what was never bought. If `put` fails, read whether the message says the account has
+already paid: when it has, the same command finishes the job for nothing more; when it has not,
+nothing was spent. `CHAIN_UNCERTAIN` is the one refusal where retrying can pay twice — run
+`nmts ls` and look for the file first.
+
+A name already taken in that folder is decided by this machine's setting (`nmts help on-collision`).
+The default numbers the new file and leaves what is there alone.
+
+**`--pay wallet`** buys the storage from the wallet your NMTS key derives instead of from
+credits, and signs. It is a standing choice: locked until a person runs `nmts unlock wallet` (scope
+`storage` is enough), and asked nothing afterwards while that unlock lasts. Before anything is
+signed it prints the review: the WAL price, the relay's tip in SUI, the chain fee measured by a dry
+run (`null` in `--json` when it could not be measured, never 0), both balances, and the term
+(`--epochs`, default 2). A wallet short of either exits 4 with the two numbers. `--storage
+fit|whole|<object id>` uses a free storage resource the wallet holds for a one-part file: `fit`
+cuts it to size and leaves the rest free, `whole` binds all of it with the file. Do not choose
+`--storage` for the person: the leftover is their decision. `--epochs` and `--storage` without
+`--pay wallet` exit 2.

package/docs/commands/rebuild.md

@@ -0,0 +1,13 @@
+# nmts rebuild, rollback — the file list itself
+
+Commands: rebuild, rollback
+Tiers: rebuild=medium · rollback=high(rollback)
+
+`rebuild` builds a file list from the server's rows, for an account that has none on this machine
+and none on the server; `--force` rebuilds one this machine has already seen a list for. In the
+default mode it asks first (or takes `--yes`); in an auto mode it is your judgement.
+
+`rollback` puts the previous file list back. Nothing can say on somebody's behalf that the list
+they are looking at is the wrong one, so it is locked until a person runs `nmts unlock rollback`,
+and then needs `--yes` on every run in every mode but skip-permissions; without it the run says
+what would happen and changes nothing.

package/docs/commands/recovery.md

@@ -0,0 +1,18 @@
+# nmts recovery, recovery-list, kit — for the day NMTS is not there
+
+Commands: recovery, recovery-list, kit
+Tiers: recovery=none · recovery-list=none · kit=high(kit)
+
+`recovery-list` writes the file that finds this account's bytes without NMTS: encrypted, it holds
+where every file's bytes are and the key that opens each, and carries no NMTS key. `kit`
+writes that list together with the NMTS key in the clear, so whoever holds that file holds the
+account and the wallet — it is locked until a person runs `nmts unlock kit`, and asked about on
+every run in every mode but skip-permissions. Both refuse to write a partial artefact and refuse a
+name already taken without `--force`. Do not make either as part of some other task, and do not
+put a kit anywhere the person did not name.
+
+`recovery` downloads the standalone program that reads files back without NMTS, one executable for
+this machine, and makes it runnable; it installs nothing and puts nothing on the PATH. Do not run
+it as part of another task: who decides to have a program on their disk is the person. The
+download is checked against the published hash, which proves the bytes are the ones published and
+does not prove the program is honest.

package/docs/commands/s3.md

@@ -0,0 +1,17 @@
+# nmts s3 — hand the drive to a program that speaks S3
+
+Commands: s3
+Tiers: s3=medium
+
+Starts a server on this machine's loopback address (`--port`, default 9000) that answers the S3
+protocol, so rclone, the AWS CLI or a backup program can list, download and upload this account's
+files without knowing NMTS. Uploads through it spend credits, which is why starting it is a medium
+act: asked once in the default mode, your judgement in an auto mode. The credentials it prints are
+made at start and stored nowhere; they stop working when the command stops.
+
+The bucket is `drive` and a key is the file's path; folders come back as common prefixes.
+Re-uploading a file that is already there is free and answered `200` — the gateway compares
+content, not names. A key holding a different file is refused with `409`: this drive does not
+replace files; delete first if replacing is what was asked for. Large files go up in pieces and an
+interrupted upload stores nothing. It runs until stopped and the address cannot be changed; start
+it for the task that needs it and stop it afterwards.

package/docs/commands/share.md

@@ -0,0 +1,15 @@
+# nmts share, shares, receive, unshare — files between accounts
+
+Commands: share, shares, receive, unshare
+Tiers: share=high(share) · shares=none · receive=none · unshare=low
+
+`share <path> <public code>` gives one file to another account. Whoever holds that code can then
+download it; withdrawing later stops further downloads and cannot recall a copy already fetched,
+and the code is not checked against a person — the wrong code sends the file to whoever holds it.
+So it is locked until a person runs `nmts unlock share` once, and then asks on every run: it prints
+the file and the code and stops until the same command is run with `--yes`, in every mode but
+skip-permissions. Sharing is also on the short list the periodic human check gates.
+
+`shares` lists what was shared with this account; `shares --sent <path>` says who one file was
+shared with. `receive <id>` downloads one shared file (`--out`, `--force` as for `get`). `unshare
+<id>` withdraws a share you sent, or removes one you were sent; in the default mode it asks once.