fidelity-ai-workspace/scripts/mattermost/README.md

Mattermost Sync

This directory contains the workspace-local Mattermost extractor used by OpenCode to refresh communication context.

The preferred live Mattermost evidence source is now the proxy mirror under ai/inbox/mattermost-mirror/ when it is running. This legacy extractor remains the fallback and explicit refresh path for commands that need a fresh pull from the Mattermost API.

Files

• mattermost_context.py Extracts recent Mattermost messages as JSONL.
• sync.sh Stable wrapper intended to be called by OpenCode.
• .env.example Example configuration without secrets.
• requirements.txt Reserved for future optional dependencies.

Recommended Setup

1. Copy .env.example to .env.
2. Fill in your Mattermost values.
3. Create a local virtual environment if you want an isolated runtime.

Preferred channel config:

• CHANNELS=fidelity-preguntas

Channel names are preferred for AI context because the exported records will use the readable channel name instead of the raw channel ID.

The script can resolve channel names without a team if the authenticated user can access the channel and the name is unique across the user's teams.

Supported env options:

• CHANNELS Mixed list of channel names or channel IDs.
• CHANNEL_NAMES Channel names only.
• CHANNEL_IDS Legacy channel IDs only.

Optional only for disambiguation:

• MATTERMOST_TEAM_NAME
• MATTERMOST_TEAM_ID

Use one of those only if the same channel name exists in multiple teams or if you want to force team-specific resolution.

Example:

cd scripts/mattermost
bash bootstrap.sh

Usage

Manual run:

bash scripts/mattermost/sync.sh

OpenCode can use this script directly. If AIW_MATTERMOST_SYNC_CMD is not set, the workspace plugins will fall back to FIDELITY_MATTERMOST_SYNC_CMD, then to this wrapper automatically.

Generic workspace variables are preferred for reusable projects:

• AIW_PROJECT_PROFILE
• AIW_CHANNEL_PREFIX
• AIW_MATTERMOST_SYNC_CMD
• AIW_MATTERMOST_SYNC_INTERVAL_MINUTES

The older FIDELITY_* variables remain supported for this project profile.

Previous workday mode for standups:

bash scripts/mattermost/sync.sh --previous-workday

This mode starts from the previous calendar day and expands backward until it finds a day with Mattermost activity in the configured channels. It handles Mondays, weekends, holidays, and OOO gaps without relying on workspace logs.

Useful options:

• --today YYYY-MM-DD
• --max-lookback-days N
• --output-file PATH

Bootstrap

You can initialize the local runtime with:

bash scripts/mattermost/bootstrap.sh

This will:

• create .venv/ if missing
• create .env from .env.example if needed

The current extractor uses only the Python standard library, so no third-party install is required.