docs: update npm README with PII model, tools, full env vars

Author: rmorse

npm/README.md

@@ -2,10 +2,10 @@
 
 A command-line interface and [MCP](https://modelcontextprotocol.io/) server for the [HelpScout](https://www.helpscout.com/) API. Manage mailboxes, conversations, customers, tags, users, workflows, webhooks, and knowledge base content from the terminal.
 
-**Built for automation and AI-assisted workflows**
-- Ships with a deterministic, layered PII redaction pipeline (structured fields + free-text + source payload protection), plus strict per-command override controls.
-- An allowlist-based permission system (`resource:operation` pairs) lets you restrict exactly which actions are permitted.
-- See [PII Redaction Pipeline](https://github.com/operator-kit/hs-cli#pii-redaction-pipeline) · [Permissions](https://github.com/operator-kit/hs-cli#permissions).
+> **Built for shared and AI-assisted workflows**
+> ML-powered, deterministic PII redaction — real identities are replaced with consistent fake ones so output stays fully readable for LLMs, debugging, and triage.
+> Allowlist-based permissions (`resource:operation` pairs) restrict exactly which actions are permitted.
+> See [PII Redaction Pipeline](https://github.com/operator-kit/hs-cli#pii-redaction-pipeline) · [Permissions](https://github.com/operator-kit/hs-cli#permissions).
 
 ## Install
 
@@ -28,37 +28,44 @@ npx -y @operatorkit/hs inbox auth login
 # Authenticate (Docs API — API key)
 npx -y @operatorkit/hs docs auth login
 
-# List mailboxes
-npx -y @operatorkit/hs inbox mailboxes list
-
 # List conversations
 npx -y @operatorkit/hs inbox conversations list --status active
 
+# Get a conversation with threads
+npx -y @operatorkit/hs inbox conversations get 67890 --embed threads
+
 # Search articles
 npx -y @operatorkit/hs docs articles search --query "getting started"
+
+# Team briefing — conversation counts per agent
+npx -y @operatorkit/hs inbox tools briefing
 ```
 
 ## Authentication
 
-The CLI uses HelpScout's OAuth2 client credentials flow. You'll need an App ID and App Secret from your HelpScout app settings:
+### Inbox API (OAuth2)
 
-> **Your Profile** > My Apps > Create App
+Requires an App ID and App Secret from your HelpScout app settings:
 
-### Interactive login (recommended for CLI)
+> **Your Profile** > My Apps > Create App
 
 ```bash
 npx -y @operatorkit/hs inbox auth login
 ```
 
-This prompts for your App ID and App Secret, validates them against the API, and stores them securely in your OS keyring.
+Prompts for your App ID and App Secret, validates them against the API, and stores them securely in your OS keyring.
+
+### Docs API (API key)
 
-### Environment variables & non interactive setup
+Requires a Docs API key from your HelpScout account:
 
-Use `npx -y @operatorkit/hs inbox config set` commands to configure authentication non-interactively or set environment variables.
+```bash
+npx -y @operatorkit/hs docs auth login
+```
 
-For MCP you can pass in the environment variables via [MCP config](#mcp-server).
+**Credential resolution order:** environment variables > OS keyring > config file.
 
-[More information and exmaples can be found here](https://github.com/operator-kit/hs-cli/#authentication);
+For non-interactive setup, use `config set` commands or pass environment variables directly. For MCP, pass credentials via [MCP config](#mcp-server).
 
 ## API coverage
 
@@ -82,6 +89,8 @@ Full CRUD for all Inbox API resources:
 - **Ratings** — get
 - **Attachments** — upload, list, get, delete
 
+See [full Inbox API reference](https://github.com/operator-kit/hs-cli/blob/main/docs/inbox-api.md) for all commands, flags, and options.
+
 ### Docs API (`hs docs ...`)
 
 Full CRUD for all Docs API resources:
@@ -93,6 +102,20 @@ Full CRUD for all Docs API resources:
 - **Redirects** — list, get, find, create, update, delete
 - **Assets** — article upload, settings upload
 
+See [full Docs API reference](https://github.com/operator-kit/hs-cli/blob/main/docs/docs-api.md) for all commands, flags, and options.
+
+### Tools (beyond the API)
+
+**Team briefing** aggregates data across multiple API calls for an instant overview of your support team's workload:
+
+```bash
+hs inbox tools briefing                                            # team overview — counts per agent
+hs inbox tools briefing --assigned-to 531600                       # agent summary — list conversations
+hs inbox tools briefing --assigned-to 531600 --embed threads       # full agent briefing with thread data
+```
+
+The briefing with `--embed threads` is particularly useful for feeding to an LLM for triage, summarisation, or draft replies.
+
 ## MCP server
 
 Start the embedded MCP server for AI-assisted workflows:
@@ -115,13 +138,34 @@ npx -y @operatorkit/hs mcp -t stdio
         "HS_INBOX_APP_ID": "your-app-id",
         "HS_INBOX_APP_SECRET": "your-app-secret",
         "HS_DOCS_API_KEY": "your-docs-api-key",
-        "HS_INBOX_PERMISSIONS": "*:read"
+        "HS_INBOX_PERMISSIONS": "*:read",
+        "HS_DOCS_PERMISSIONS": "*:read"
       }
     }
   }
 }
 ```
 
+Only the credentials for the APIs you use are required — `HS_INBOX_APP_ID` + `HS_INBOX_APP_SECRET` for Inbox, `HS_DOCS_API_KEY` for Docs. Permission and PII variables are optional.
+
+## PII redaction
+
+An ML-powered PII redaction system designed for shared terminals, MCP/LLM workflows, and incident-safe exports.
+
+- **ML-based name detection** — a multilingual NER model detects person names in freeform text (bodies, subjects, notes) and replaces them with consistent fake identities. Supports 10 languages: Arabic, Chinese, Dutch, English, French, German, Italian, Latvian, Portuguese, and Spanish.
+- **Deterministic pseudonyms** — same real identity always maps to the same fake name, email, and phone across commands and sessions. No mappings stored anywhere.
+- **Mode-aware** — `customers` mode redacts only customer data; `all` mode redacts everyone.
+- **Runs locally** — the model runs entirely on your machine via ONNX Runtime. No API calls, no data leaves your system.
+
+```bash
+hs pii-model install                                    # download model (~100 MB, one-time)
+hs pii-model status                                     # check install status
+hs inbox config set --inbox-pii-mode customers           # enable redaction
+hs inbox conversations get 12345 --embed threads         # output uses fake identities
+```
+
+Without the model installed, freeform text fields are hidden with a notice. Structured field redaction (names, emails, phones) always works regardless.
+
 ## Output formats
 
 | Format | Flag | Description |
@@ -131,12 +175,6 @@ npx -y @operatorkit/hs mcp -t stdio
 | JSON-full | `--format json-full` | Raw API response, pretty-printed |
 | CSV | `--format csv` | RFC 4180 CSV with headers |
 
-## Safety features
-
-- **PII redaction** — deterministic, layered pipeline (structured fields + free-text + source payloads). Modes: `off`, `customers`, `all`.
-- **Permissions** — allowlist-based `resource:operation` pairs restrict which actions are permitted. Set via `HS_INBOX_PERMISSIONS` / `HS_DOCS_PERMISSIONS`.
-- **Rate limiting** — built-in rate limiters respect API quotas (Inbox: 200/min, Docs: 2000/10min).
-
 ## Environment variables
 
 | Variable | Description |
@@ -146,12 +184,18 @@ npx -y @operatorkit/hs mcp -t stdio
 | `HS_DOCS_API_KEY` | Docs API key |
 | `HS_FORMAT` | Default output format |
 | `HS_INBOX_PII_MODE` | PII redaction mode: `off`, `customers`, `all` |
+| `HS_INBOX_PII_ALLOW_UNREDACTED` | Allow `--unredacted` bypass |
+| `HS_INBOX_PII_SECRET` | Secret salt for deterministic pseudonyms |
 | `HS_INBOX_PERMISSIONS` | Inbox permission policy |
 | `HS_DOCS_PERMISSIONS` | Docs permission policy |
+| `HS_NO_UPDATE_CHECK` | Disable daily update check (`1`) |
 
 ## Links
 
 - [GitHub](https://github.com/operator-kit/hs-cli)
+- [Inbox API reference](https://github.com/operator-kit/hs-cli/blob/main/docs/inbox-api.md)
+- [Docs API reference](https://github.com/operator-kit/hs-cli/blob/main/docs/docs-api.md)
+- [Developer guide](https://github.com/operator-kit/hs-cli/blob/main/DEVELOPMENT.md)
 - [Issues](https://github.com/operator-kit/hs-cli/issues)
 - [HelpScout API docs](https://developer.helpscout.com/)