Metadata-Version: 2.4
Name: navig-matrix
Version: 0.1.0
Summary: Matrix messaging surface for navig — rooms, invites, tokens, admin and the inbox bridge, as its own plugin.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Keywords: navig,matrix,messaging,rooms,plugin
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: navig>=3.25.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"

# navig-matrix

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Matrix messaging surface for navig — rooms, invites, tokens, admin and the inbox bridge, as its own plugin.

**A navig extension** — installing it pulls in navig and adds the commands below · v0.1.0 · not on PyPI yet (install from source below)

**Install**

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-matrix"
```

It is not a separate program: it needs navig, and installing it installs navig for you.

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig matrix accounts` | List configured Matrix accounts from the vault. |
| `navig matrix bridge deploy` | Pull and start all mautrix bridge containers via Docker. |
| `navig matrix bridge logs` | Tail logs from a mautrix bridge container. |
| `navig matrix bridge restart` | Restart a mautrix bridge container. |
| `navig matrix bridge setup` | Interactive setup wizard for a mautrix bridge. |
| `navig matrix bridge status` | Show running state of all mautrix bridges. |
| `navig matrix e2ee blacklist` | Blacklist a device (do not send keys to it). |
| `navig matrix e2ee devices` | List devices and their trust state. |
| `navig matrix e2ee export-keys` | Export E2EE room keys to a file (encrypted). |
| `navig matrix e2ee import-keys` | Import E2EE room keys from a file. |
| `navig matrix e2ee keys` | Show the bot's own device keys (for cross-verification). |
| `navig matrix e2ee status` | Show E2EE diagnostic status. |
| `navig matrix e2ee trust` | Manually trust a device (skip SAS verification). |
| `navig matrix e2ee trust-all` | Trust ALL known devices for a user. |
| `navig matrix e2ee unverify` | Remove trust from a device. |
| `navig matrix e2ee verify` | Start interactive SAS (emoji) verification with a device. |
| `navig matrix features` | Show Matrix feature toggle states. |
| `navig matrix file download` | Download a file from a Matrix content URI. |
| `navig matrix file upload` | Upload a file to a Matrix room. |
| `navig matrix inbox list` | List persisted Matrix inbox messages. |
| `navig matrix inbox mark-read` | Mark messages as read (one or all). |
| `navig matrix inbox process` | Route unread Matrix messages through InboxRouterAgent. |
| `navig matrix inbox purge` | Delete all read messages from inbox. |
| `navig matrix inbox unread` | Show unread count. |
| `navig matrix login` | Authenticate with a Matrix homeserver. |
| `navig matrix logout` | End the current Matrix session. |
| `navig matrix notice` | Send a notice (bot-style, no notification highlight). |
| `navig matrix read` | Read recent messages from a room. |
| `navig matrix rooms` | List joined Matrix rooms. |
| `navig matrix send` | Send a text message to a Matrix room. |
| `navig matrix status` | Show Matrix connection status and account info. |
| `navig matrix store bridges` | List bridge configurations in the store. |
| `navig matrix store events` | Show recent events for a room from the persistent store. |
| `navig matrix store prune` | Prune old events from the store. |
| `navig matrix store rooms` | List rooms in the persistent store. |
| `navig matrix store set-purpose` | Classify what a stored room is FOR. |
| `navig matrix store stats` | Show persistent store statistics. |
| `navig matrix tail` | Live-tail messages from a room (Ctrl+C to stop). |
| `navig matrix use` | Switch the active Matrix account. |

</details>

<!-- navig:plugin-card:end -->

**The Matrix messaging surface for navig** — rooms, invites, tokens, admin and the inbox
bridge, shipped as its own plugin instead of 39 commands inside core.

```powershell
pip install -e plugins/navig-matrix --no-deps
navig matrix --help          # same verbs as before, now owned here
navig mx --help              # the hidden alias still points at the same app
```

## Why a plugin

Core carried `navig/commands/matrix.py` (71 KB, 39 commands) while nothing else in core used
it. It is a domain with a lifecycle — installable, versionable, uninstallable — so it belongs
in a plugin. The comms layer it drives (`navig.comms.matrix`, `navig.comms.matrix_features`)
stays in core, where other surfaces read it too; this package is the CLI over it.

## How it mounts

Core keeps the `matrix` / `mx` verb in its command map pointing at
`core/navig/commands/matrix.py`, which is now a five-line alias to
`navig_matrix.commands.matrix` (the same shape as `navig.commands.cdp` → `navig-browser`).
That means:

- `navig matrix …`, `navig mx …`, and the deck/OS surfaces behave exactly as before;
- with the package absent, the verb still exists and says how to install it, instead of
  disappearing from `navig --help`;
- `navig.commands.matrix` stays importable, so the 153 tests in
  `core/tests/core/test_matrix.py` did not have to move or change.

## Commands

`rooms` · `room` (create/join/leave/invite) · `registration` + `token` (invite tokens) ·
`admin` (server administration) · `inbox` (bridge) · `send` · `sync` · `whoami` · `verify` ·
`login` · `logout` · `status` · `users` · `devices` · `rooms-dm` — see `navig matrix --help`.

## Verify

```powershell
py -m pytest core/tests/core/test_matrix.py -q      # 153 passed
navig matrix --help                                 # same surface as the core module had
```
