Negative-Star-Innovators · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026
diff --git a/.gitignore b/.gitignore
@@ -27,9 +27,6 @@ cloudflare/.dev.vars
 # Store submission content (kept out of the repo)
 windows/store-listing/
 
-# Internal planning docs (not for public release)
-docs/linux-port-plan.md
-
 # Translation/CI tooling venv (lrelease, deep-translator)
 .transvenv/
 

diff --git a/README.md b/README.md
@@ -68,6 +68,10 @@ website:
 - [OpenCode](https://agentredactor.negativestarinnovators.com/opencode.html)
 - [Hermes](https://agentredactor.negativestarinnovators.com/hermes.html)
 
+The engine binary also doubles as a scriptable CLI (`agentredactor status`,
+`keywords add`, `profiles add`, …) for terminals, scripts, and headless
+machines — see [docs/cli.md](docs/cli.md).
+
 ## Repository layout
 
 | Path | Contents |
@@ -77,7 +81,7 @@ website:
 | `core/` | OS-agnostic C++ core (HTTP proxy, ONNX NER, regex/redaction engines, CLI) shared by the platform frontends; built by both the Windows and Linux projects |
 | `cloudflare/` | The Cloudflare worker + R2 behind the self-release channel (`/install.ps1`, `/install.sh`, `/updates`, `/models`) |
 | `website/` | The website with the agent integration guides, translated into every supported language |
-| `docs/` | Design and spec documents (Linux implementation spec, port plan) |
+| `docs/` | Additional documentation — currently the [CLI reference](docs/cli.md) |
 | `tests/` | pytest suites: cross-platform `cli/` and `migration/`, Linux GUI tests in `linux/` (AT-SPI), Windows GUI end-to-end tests in `gui/` (FlaUI + mock LLM), self-release install/upgrade E2E |
 | `third_party_tests/` | Integration tests driving real third-party agent CLIs through the proxy |
 | `scripts/` | Build/release helpers and scripts that configure third-party clients for the integration tests |

diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,132 @@
+# Agent Redactor CLI
+
+The Agent Redactor engine binary doubles as a command-line interface. On
+Windows it ships as `agentredactor.exe` next to the GUI (the Microsoft Store
+package also registers an `agentredactor` AppExecutionAlias); on Linux the
+installer symlinks `agentredactor` into `~/.local/bin`, and AppImage
+invocations are forwarded to the same binary.
+
+Every command talks to the *running* engine over its localhost control API, so
+the CLI and the GUI always agree on state — use either, interchangeably.
+
+- Output goes to the console, or UTF-8 to stdout when piped (script-friendly).
+- Exit codes: `0` success, `1` runtime error, `2` usage error.
+- `agentredactor help` prints the built-in reference; it is always in sync
+  with the binary you have installed.
+- Quote regex patterns containing `{ } [ ]` etc. so the shell does not expand
+  them — bash: single quotes, PowerShell/cmd: double quotes, e.g.
+  `agentredactor regex add 'sk-[a-zA-Z0-9]{20,}'`.
+
+## Commands
+
+### Overview
+
+```text
+agentredactor status            engine + profile overview (ungated)
+agentredactor languages         list supported UI language codes (ungated)
+agentredactor download-model    download the AI model weights (first run; shows progress)
+```
+
+On Linux, `status` additionally checks the update feed and prints an
+"update available" line when a newer release exists.
+
+### Settings and profiles
+
+```text
+agentredactor get <key> [--profile P]          read a setting
+agentredactor set <key> <value> [--profile P]  change a setting
+agentredactor profiles list                    list profiles (with request/redaction stats)
+agentredactor profiles add <alias> [--port N] [--upstream-url U] [--api-key K]
+agentredactor profiles delete <id>
+```
+
+- `--profile P` selects a profile by list number, id, or alias (optional when
+  only one profile exists).
+- Without `--port`, `profiles add` picks the first free port from 8080 and
+  prints the created profile's id.
+- `profiles delete` accepts only the profile id (never an alias or list
+  number) and refuses to delete the last profile.
+
+Global keys: `start-on-boot`, `logging`, `show-sensitive`, `app-language`.
+
+Profile keys: `alias`, `upstream-url`, `api-key`, `port`,
+`confidence-threshold` (0..1), `use-ai-model`.
+
+`app-language` must be an exact supported BCP-47 tag — the values are what
+`agentredactor languages` prints (`en`, `de`, `zh-CN`, …); a partial tag like
+`zh` is rejected.
+
+### Redaction lists (profile-scoped)
+
+```text
+agentredactor regex list [--profile P]
+agentredactor regex add <pattern> [--profile P]
+agentredactor regex remove <n|pattern> [--profile P]
+agentredactor keywords list [--profile P]
+agentredactor keywords add <text> [--ignore-case] [--profile P]
+agentredactor keywords remove <n|text> [--ignore-case] [--profile P]
+agentredactor pii-types list [--profile P]
+agentredactor pii-types enable | disable <type> [--profile P]
+```
+
+- `pii-types` deals in single PII types only (no categories): `account_number`,
+  `private_address`, `private_date`, `private_email`, `private_person`,
+  `private_phone`, `private_url`, `secret`.
+- Duplicates are rejected on add: a keyword is a duplicate when both text and
+  case-sensitivity match; a regex when the normalized pattern matches
+  (`{,5}` == `{0,5}`).
+- `keywords remove <text>` selects a case-insensitive entry with
+  `--ignore-case`; without it, the first case-sensitive match, falling back to
+  an ignore-case entry.
+
+### Security
+
+```text
+agentredactor password enable
+agentredactor password disable
+```
+
+- **Windows:** enables/disables Windows Hello protection. With protection on,
+  every read/write command demands a fresh Hello consent (`status` and `help`
+  stay open).
+- **Linux:** enables/disables a typed master password. With protection on,
+  every read/write command prompts for it (`status` and `help` stay open).
+
+### Maintenance (Linux only)
+
+```text
+agentredactor update             check for and install AppImage updates
+agentredactor uninstall [--yes]  remove Agent Redactor, settings, icons, and the AppImage
+```
+
+`update` swaps the AppImage for the latest release on its update channel;
+restart to apply (`systemctl --user restart agentredactor` on headless
+installs). `uninstall` asks for confirmation unless `--yes` is given.
+
+## Scripting examples
+
+```bash
+# Is the engine up? (on Linux this also reports when an update is available)
+agentredactor status
+
+# Add a keyword from a script; a duplicate is rejected with a clear message
+agentredactor keywords add "internal-codename" --ignore-case
+
+# Turn off phone-number redaction on the default profile
+agentredactor pii-types disable private_phone
+
+# Headless server: point a new agent profile at OpenRouter
+agentredactor profiles add openrouter \
+  --upstream-url https://openrouter.ai/api/v1 --api-key sk-or-...
+
+# Review the result
+agentredactor profiles list
+```
+
+## Notes
+
+- There is deliberately no `engine run` / `engine stop`: engine lifecycle
+  belongs to the GUI (or the systemd user service on headless Linux).
+- On Linux the model weights download automatically on first engine start;
+  `download-model` exists so a fresh headless install can bootstrap without
+  waiting (`install.sh` already runs it for you).
diff --git a/linux/README.md b/linux/README.md
@@ -1,7 +1,8 @@
 # Agent Redactor — Linux build
 
 For installing and *using* Agent Redactor (end users), see the
-[root README](../README.md) — this document covers building and developing
+[root README](../README.md), and for the scriptable `agentredactor` CLI see
+[docs/cli.md](../docs/cli.md) — this document covers building and developing
 on Linux.
 
 Build the engine/CLI (`agentredactor`) and the Qt GUI (`agentredactor-gui`)

diff --git a/windows/AGENTS.md b/windows/AGENTS.md
@@ -67,6 +67,11 @@ Key sources:
 
 ## CLI
 
+The user-facing CLI reference lives in `../docs/cli.md` — update it when
+`../core/src/cli.cpp` changes. The notes below are maintainer detail (password
+model, transport quirks, test hooks) that intentionally stays out of the user
+docs.
+
 `agentredactor.exe` doubles as the CLI; every subcommand talks to the running
 engine over the control API (so CLI and GUI always agree). Output goes to the
 inherited console, or UTF-8 to stdout when piped (script/AI-agent friendly);

diff --git a/windows/README.md b/windows/README.md
@@ -107,7 +107,9 @@ From the `windows` folder:
 
 ## Configuration
 
-Settings are stored in `%APPDATA%\AgentRedactor\settings.json`.
+Settings are stored in `%APPDATA%\AgentRedactor\settings.json`. Everything in
+this section can also be driven from the scriptable `agentredactor` CLI —
+see [../docs/cli.md](../docs/cli.md).
 
 ### Default Profile Setup