feat: implement Mattermost proxy mirror with configuration and scripts for capturing traffic

scripts/mattermost-proxy/README.md

@@ -0,0 +1,107 @@
+# Mattermost Proxy Mirror
+
+Local read-only Mattermost Desktop mirror for AI workspace context.
+
+This is for **raw evidence only**. It writes under `ai/inbox/mattermost-mirror/`; durable project memory still belongs in `project-knowledge/` after normal promotion rules.
+
+## Why this exists
+
+Mattermost Team Edition 11.4.2 exposes normal `/api/v4` REST and WebSocket traffic. When Mattermost Desktop is launched with Chromium/Electron's `--proxy-server` flag, `mitmproxy` can capture only that app without changing the macOS system proxy.
+
+## Setup
+
+1. Install `mitmproxy`.
+2. Trust the mitmproxy certificate if HTTPS interception is not already working:
+   - Start `scripts/mattermost-proxy/run-mirror.sh`
+   - Open `http://mitm.it`
+   - Install/trust the certificate in Keychain.
+3. Optional: copy `.env.example` to `.env` and set `MATTERMOST_MIRROR_HOST_ALLOW` to the exact Mattermost host.
+
+## Run day to day
+
+Terminal 1:
+
+```bash
+scripts/mattermost-proxy/run-mirror.sh
+```
+
+Terminal 2:
+
+```bash
+scripts/mattermost-proxy/launch-mattermost.sh
+```
+
+This launches Mattermost Desktop through macOS LaunchServices with:
+
+```bash
+--proxy-server=http://127.0.0.1:8080
+```
+
+No global macOS proxy is required.
+
+The helper intentionally uses `open -n /Applications/Mattermost.app --args ...`
+instead of invoking `/Applications/Mattermost.app/Contents/MacOS/Mattermost`
+directly. Direct binary launch can crash sandboxed Electron apps with Mach
+rendezvous errors because their expected app/container parent process is
+missing. If you need the old behavior for debugging, set:
+
+```bash
+MATTERMOST_MIRROR_LAUNCH_MODE=binary scripts/mattermost-proxy/launch-mattermost.sh
+```
+
+## Output layout
+
+```text
+ai/inbox/mattermost-mirror/
+  latest.jsonl              # bounded AI-readable window
+  latest.md                 # bounded Markdown view
+  state.json                # last seen by channel and user cache
+  index.json                # date/channel file map
+  messages/YYYY/MM/YYYY-MM-DD.jsonl
+  raw/YYYY/MM/YYYY-MM-DD-websocket.jsonl     # only if MATTERMOST_MIRROR_WRITE_RAW=1
+  raw/YYYY/MM/YYYY-MM-DD-rest-flows.jsonl    # only if MATTERMOST_MIRROR_WRITE_RAW=1
+```
+
+Use `latest.md` or `latest.jsonl` for quick AI context. Use date-rotated `messages/...` files for previous-workday or channel/date-specific analysis.
+
+## Normalized message schema
+
+Each line in the normalized JSONL contains:
+
+```json
+{
+  "source": "websocket|rest",
+  "captured_at": "2026-05-19T...Z",
+  "created_at": "2026-05-19T...Z",
+  "created_at_ms": 1779190000000,
+  "channel_id": "...",
+  "channel_name": "fidelity-preguntas",
+  "post_id": "...",
+  "root_id": "...",
+  "thread_id": "...",
+  "user_id": "...",
+  "username": "jeff",
+  "message": "...",
+  "type": "channel_post|thread_reply",
+  "raw_event": "posted|posts|post"
+}
+```
+
+## Safety rules
+
+- The addon allowlists Mattermost hosts and `/api/v4` traffic only.
+- Headers such as `Authorization`, `Cookie`, `Set-Cookie`, and CSRF are redacted in optional raw output.
+- Optional raw output is disabled by default to prevent large files.
+- Attachments are not downloaded by this mirror.
+- The mirror is evidence, not canonical memory.
+
+## Useful environment variables
+
+- `MATTERMOST_MIRROR_HOST_ALLOW`: exact host or parent domain to capture.
+- `MATTERMOST_MIRROR_DIR`: output directory, default `ai/inbox/mattermost-mirror`.
+- `MATTERMOST_MIRROR_LATEST_LIMIT`: number of messages in `latest.*`, default `200`.
+- `MATTERMOST_MIRROR_CHANNEL_IDS`: optional comma-separated channel ID allowlist.
+- `MATTERMOST_MIRROR_WRITE_RAW`: set to `1` to save compact raw REST/WebSocket evidence.
+- `MATTERMOST_APP_BIN`: Mattermost Desktop binary path.
+- `MATTERMOST_APP_PATH`: Mattermost Desktop `.app` bundle path.
+- `MATTERMOST_MIRROR_LAUNCH_MODE`: `open` by default; `binary` only for debugging.