Refresh Mantis CLI and quickstart documentation

README.md

@@ -32,7 +32,7 @@ Components are versioned independently: the server, the CLI, and the edge worker
 
 ## What it does
 
-- **File keys** in 10 formats (`.docx` / `.xlsx` / `.pptx` / `.pdf` / `.svg` / `.html` / `.md` / `.eml` / `.ics` / `.vcf`) plus a honey-directory `.zip` and Apple Wallet `.pkpass` passes (install / uninstall / fetch callbacks each fire the key)
+- **File keys** in 11 formats (`.docx` / `.xlsx` / `.pptx` / `.pdf` / `.rtf` / `.svg` / `.html` / `.md` / `.eml` / `.ics` / `.vcf`) plus credential and connection-profile bait, a honey-directory `.zip`, and Apple Wallet `.pkpass` passes (install / uninstall / fetch callbacks each fire the key)
 - **Host-event installers** — shell, sudo, login, boot, wake, network — for macOS, Linux, and Windows, with parsed `X-Mantis-*` context including SSH client IP
 - **Web canaries** — CSS-background and JS clone-detector — plus NFC NDEF tag URLs and printable QR/NFC sticker labels
 - **Smart-home triggers** via Home Assistant, Scrypted, and an optional LAN watcher
@@ -85,6 +85,7 @@ The prose documentation lives at [docs.mantis.privacykey.org](https://docs.manti
 
 - [Getting started](https://docs.mantis.privacykey.org/getting-started) — five steps from `brew install` to first key
 - [Use cases](https://docs.mantis.privacykey.org/use-cases) — defensive, detective, operational and adversarial patterns
+- [CLI reference](https://docs.mantis.privacykey.org/cli/) and [command map](./cli/COMMAND_MAP.md) — setup, key management, monitoring, and scripting
 - [HTTP API](https://docs.mantis.privacykey.org/api) — endpoints, response kinds, webhook payload shape
 - [File keys](https://docs.mantis.privacykey.org/file-keys), [host-event keys](https://docs.mantis.privacykey.org/host-events), [deployment](https://docs.mantis.privacykey.org/deployment), [updating](https://docs.mantis.privacykey.org/updating)
 - [`CHANGELOG.md`](./CHANGELOG.md) — what changed in each release, with the upgrade steps (migrations, settings, artifacts to regenerate)

cli/README.md

@@ -7,14 +7,18 @@ For a visual overview of every command and how they relate, see
 
 ## Install (from this repo)
 
+From the repository root, use the Node version in [`.nvmrc`](../.nvmrc)
+and the pnpm version pinned in [`package.json`](../package.json).
+
 ```bash
-cd cli
-npm install
-npm run build
-npm link            # exposes `mantis` on $PATH
+pnpm install --frozen-lockfile
+pnpm --filter @mantis/cli run build
+node cli/dist/index.js --help
 ```
 
-For one-off use without linking: `node cli/dist/index.js <command>`.
+For the published binary, run `brew install privacykey/tap/mantis`. This
+README follows the source tree, so terminal examples can differ from the
+version installed by Homebrew.
 
 ## Quickstart
 
@@ -39,6 +43,24 @@ Credentials are stored in:
 - OS keychain (`mantis-cli-cf` service, account = base URL) — Cloudflare Access service-auth credentials (if configured)
 - `~/.cloudflared/` — short-lived JWTs cached by the `cloudflared` binary itself (managed externally; we don't touch them)
 
+## Reading the terminal output
+
+Run `mantis --help` for commands grouped by task, or
+`mantis <command> --help` for its options. Running `mantis` with no arguments
+shows next steps based on whether you have a server profile, an edge key, or
+both.
+
+- `mantis status` puts tripped keys first and reports unavailable monitor
+  states. Run `mantis status <id>` for the hits behind a trip, or
+  `mantis status --watch` for a live view.
+- `mantis hits <id>` shows recent hits. Use `--verbose` for full headers or
+  `--follow` to see new hits as they arrive.
+- `mantis doctor` lists passed, skipped, and failed checks with next steps
+  where available. Use it after setting up a profile or changing hosts.
+
+Use [machine-readable output](#scripting) when another program consumes the
+result.
+
 ## Commands
 
 | Command | Purpose |

cli/share/man/man1/mantis.1

@@ -213,7 +213,7 @@ Poll across all keys (or one) and print new hits as they arrive.
 .B mantis status [id] [\-w] [\-\-tripped\-only] [\-i N]
 Show monitor state. Without
 .IR id :
-summary across all monitored keys. With
+summary across all monitored keys, with tripped keys first. With
 .IR id :
 detail (window: hits + expiry; latch: hits since reset).
 .BR \-w / \-\-watch
@@ -291,7 +291,8 @@ and vectors with a server-side dedupe window are chattier on edge.
 .TP
 .B mantis doctor [\-\-public\-url URL]
 Health-check CLI config, server health, auth, Cloudflare state, and split
-public/private hosts.
+public/private hosts. The report distinguishes failed and skipped checks
+and shows recovery steps where available.
 
 .TP
 .B mantis detect [\-\-scope user|system|all] [\-\-deep] [\-\-verbose]
@@ -462,6 +463,9 @@ mantis detect \-\-scope all \-\-deep
 .RE
 
 .SH SEE ALSO
+CLI reference at
+.UR https://docs.mantis.privacykey.org/cli/
+.UE .
 Project README at
 .UR https://github.com/privacykey/mantis
 .UE

cli/share/tldr/mantis.md

@@ -16,7 +16,7 @@
 
 `mantis hits last --follow`
 
-- Create a key with a decoy PDF that fires when the file is opened:
+- Create a key and a decoy PDF that can fire in a compatible reader:
 
 `mantis new "{{memo}}" --pdf {{path/to/decoy.pdf}}`
 

docs/GETTING-STARTED.md

@@ -1,8 +1,5 @@
 # Getting started
 
-Moved out of the top-level README so it stays short. Everything here was in the
-README before; nothing has been added.
-
 **Stateful server or stateless edge?** Run the full **server** (`docker compose`,
 Postgres-backed) when you want the web dashboard, notification queue,
 file/host-event keys, and history. Run the **edge**
@@ -41,8 +38,10 @@ Open <http://localhost:3000> and paste that same key to sign in to the web
 dashboard. Then log in the CLI and mint a key:
 
 ```bash
-mantis --key mantis_live_... login --url http://localhost:3000
-mantis new "first mantis" -w http://localhost:3000/inbox/demo
+mantis login --url http://localhost:3000   # paste the admin key when prompted
+key_id="$(mantis new "first mantis" --id-only)"
+curl -fsS -o /dev/null "$(mantis show "$key_id" --url-only)"
+mantis hits "$key_id"
 ```
 
 This is fine for evaluation but **don't rely on a laptop deploy for canaries