{
  "schema_version": 1,
  "skill_name": "meshcore-packet-capture",
  "evals": [
    {
      "id": "neighbors-now-cli",
      "prompt": "A user wants to run a single neighbors discovery + scopes cycle against their connected MeshCore companion right now, then have the capture process keep running afterward. Which meshcore-packet-capture CLI flag combination triggers one cycle immediately without quitting? What flag would make it exit after the cycle?",
      "expected_output": "--neighbors-now runs one cycle immediately; --neighbors-exit (combined with --neighbors-now) exits once the cycle finishes.",
      "assertions": [
        "response_contains:--neighbors-now",
        "response_contains:--neighbors-exit",
        "exit_status:completed",
        "activation_evidence_contains:meshcore-packet-capture"
      ],
      "files": ["SKILL.md", "references/configuration.md"]
    },
    {
      "id": "neighbors-broker-optin",
      "prompt": "A deployment publishes packet captures to an MQTT broker but no neighbors snapshot ever appears, even though the firmware supports it. The capture logs show a connected radio and healthy broker. What per-broker config must be set, and what additional requirement exists for the neighbors topic?",
      "expected_output": "The broker block must set neighbors = true, and an IATA (or an explicit [broker.topics] neighbors override) is required; the cycle only runs when at least one enabled broker opts in.",
      "assertions": [
        "response_contains:neighbors = true",
        "response_contains:IATA",
        "exit_status:completed",
        "activation_evidence_contains:meshcore-packet-capture"
      ],
      "files": ["SKILL.md", "references/configuration.md"]
    },
    {
      "id": "payload-decoding-limits",
      "prompt": "With decode_payloads enabled, which MeshCore packet types gain a nested decoded object, and which type remains opaque to a passive observer?",
      "expected_output": "GRP_TXT channel messages are decrypted (sender, text) and ADVERTs are parsed (name, role, lat/lon); direct TXT_MSG messages cannot be decrypted by a passive observer.",
      "assertions": [
        "response_contains:GRP_TXT",
        "response_contains:TXT_MSG",
        "response_contains:decoded",
        "exit_status:completed",
        "activation_evidence_contains:meshcore-packet-capture"
      ],
      "files": ["SKILL.md", "references/configuration.md"]
    },
    {
      "id": "user-service-install",
      "prompt": "A Linux user has a local checkout of meshcore-packet-capture and wants a per-user systemd service without root install under /opt or /etc. What installer invocation creates it, and what command removes it later?",
      "expected_output": "./install.sh --user-service creates the per-user service (optionally with --repo-dir PATH); ./uninstall.sh --user-service removes it, with --remove-venv to also delete the local .venv.",
      "assertions": [
        "response_contains:--user-service",
        "response_contains:--repo-dir",
        "response_contains:--remove-venv",
        "exit_status:completed",
        "activation_evidence_contains:meshcore-packet-capture"
      ],
      "files": ["SKILL.md", "references/deployment-and-troubleshooting.md"]
    },
    {
      "id": "config-precedence",
      "prompt": "In meshcore-packet-capture, which source wins when the same setting appears in the process environment, an explicit --config TOML file, and a .env file? Where should a user put their own overrides on a managed install?",
      "expected_output": "Real process environment variables win over TOML, which wins over .env; user overrides belong in /etc/meshcore-packet-capture/config.d/99-user.toml (kept after updates).",
      "assertions": [
        "response_contains:99-user.toml",
        "response_contains:environment",
        "exit_status:completed",
        "activation_evidence_contains:meshcore-packet-capture"
      ],
      "files": ["SKILL.md", "references/configuration.md"]
    }
  ]
}

# Configuration reference

Source basis: `agessaman/meshcore-packet-capture` commit `c011f4e` (v2.2.0), inspected 2026-08-09. Re-check upstream before relying on version-sensitive details.

## TOML layout

The primary file is `/etc/meshcore-packet-capture/config.toml`. Sorted `config.d/*.toml` files are applied afterward. The installer puts presets in `config.d/10-*.toml`; put local changes in `config.d/99-user.toml`.

```toml
[general]
iata = "SEA"
log_level = "INFO"

[topics]
status = "meshcore/{IATA}/{PUBLIC_KEY}/status"
packets = "meshcore/{IATA}/{PUBLIC_KEY}/packets"
# raw = "meshcore/{IATA}/{PUBLIC_KEY}/raw"
# neighbors = "meshcore/{IATA}/{PUBLIC_KEY}/neighbors"

[capture]
connection_type = "ble"       # ble, serial, tcp
timeout = 30
data_dir = "/var/lib/meshcore-packet-capture/data"
max_connection_retries = 5    # 0 means infinite
connection_retry_delay = 5
health_check_interval = 30
advert_interval_hours = 47     # 0 disables periodic adverts

# Payload decoding (v2.1.0+): adds a nested "decoded" object with
# plain-text / structured fields. GRP_TXT channel messages are decrypted
# (sender, text), ADVERTs parsed (name, role, lat/lon), plus type/route labels.
# decode_payloads = false
# include_decoded = false           # global default; opt in per broker below
# decode_hashtag_channels = ["bot", "weather"]
# decode_channel_keys = "name=hexOrBase64,other=..."
# decode_include_public = true

# Neighbors publishing (v2.1.0+): periodic zero-hop neighbor table + each
# neighbor's region scopes. Off by default; enabled per broker with
# neighbors = true. Interval clamped to 12-336 hours.
# neighbors_interval_hours = 24
# neighbors_discover_window = 60
# neighbors_command_timeout = 20
# neighbors_scope_timeout = 0      # 0 = use device's own estimate
# neighbors_scope_min_timeout = 8
# neighbors_scope_gap = 2.0
# neighbors_cycle_timeout = 600
# neighbors_max = 32
# neighbors_self_scopes = ""

# Log rotation (v2.1.0+): only when --output is used
# log_rotation = "off"             # off | size | time
# log_max_bytes = "50MB"
# log_rotation_when = "midnight"
# log_backup_count = 5

[serial]
ports = ["/dev/ttyUSB0"]
baud_rate = 115200
timeout = 2

[[broker]]
name = "home"
enabled = true
server = "mqtt.example.com"
port = 1883
transport = "tcp"
keepalive = 60
qos = 0
retain = false
# include_decoded = true   # publish the "decoded" object to this broker
# neighbors = false        # publish the neighbors snapshot to this broker

[broker.auth]
method = "password"            # password, token, or none
username = "user"
password = "secret"

[broker.tls]
enabled = false
verify = true

[broker.topics]
packets = "custom/{IATA}/{PUBLIC_KEY}/packets"
```

`[capture]` also accepts `tcp_host`, `tcp_port`, `ble_address`, `ble_device_name`, `ble_pin` (v2.1.0+, optional six-digit PIN for BLE connections; Linux may still require BlueZ pairing during first-time setup), `origin`, `private_key`, `private_key_file`, retry/backoff controls, stats controls, `drain_messages`, TCP keepalive controls, `upload_packet_types`, `exit_on_reconnect_fail`, and binary-interface controls. `config.toml.example` in the upstream repository is the authoritative complete list.

## Precedence and merging

Runtime precedence is:

1. Variables already present in the process environment.
2. Explicit `--config PATH` files, in argument order, or the default `/etc/.../config.toml` plus sorted `config.d/*.toml`.
3. `.env.local`, then `.env`.

There is an important implementation detail: the application snapshots the real process environment before reading dotenv files. TOML may replace a value sourced only from `.env`, but never replaces a real process variable.

TOML dictionaries deep-merge. Broker arrays merge by non-empty `name`; a same-named broker is deep-merged, and a new broker is appended. Disabled brokers are omitted when flattening to MQTT slots. Because the runtime discovers slots sequentially, keep enabled broker entries contiguous as `MQTT1`, `MQTT2`, and so on.

## Environment names

Every flat runtime setting uses the `PACKETCAPTURE_` prefix:

- Connection: `PACKETCAPTURE_CONNECTION_TYPE`, `PACKETCAPTURE_BLE_ADDRESS`, `PACKETCAPTURE_BLE_DEVICE_NAME`, `PACKETCAPTURE_BLE_PIN`, `PACKETCAPTURE_SERIAL_PORTS`, `PACKETCAPTURE_TCP_HOST`, `PACKETCAPTURE_TCP_PORT`.
- Runtime: `PACKETCAPTURE_TIMEOUT`, `PACKETCAPTURE_MAX_CONNECTION_RETRIES`, `PACKETCAPTURE_CONNECTION_RETRY_DELAY`, `PACKETCAPTURE_HEALTH_CHECK_INTERVAL`, `PACKETCAPTURE_DRAIN_MESSAGES`, `PACKETCAPTURE_STATS_IN_STATUS_ENABLED`, `PACKETCAPTURE_STATS_REFRESH_INTERVAL`.
- Identity/topics: `PACKETCAPTURE_IATA`, `PACKETCAPTURE_ORIGIN`, `PACKETCAPTURE_TOPIC_STATUS`, `PACKETCAPTURE_TOPIC_PACKETS`, `PACKETCAPTURE_TOPIC_DECODED`, `PACKETCAPTURE_TOPIC_DEBUG`, `PACKETCAPTURE_TOPIC_RAW`, `PACKETCAPTURE_TOPIC_NEIGHBORS`.
- Decoding (v2.1.0+): `PACKETCAPTURE_DECODE_PAYLOADS`, `PACKETCAPTURE_INCLUDE_DECODED`, `PACKETCAPTURE_DECODE_HASHTAG_CHANNELS`, `PACKETCAPTURE_DECODE_CHANNEL_KEYS`, `PACKETCAPTURE_DECODE_INCLUDE_PUBLIC`.
- Neighbors (v2.1.0+): `PACKETCAPTURE_NEIGHBORS_INTERVAL_HOURS`, `PACKETCAPTURE_NEIGHBORS_DISCOVER_WINDOW`, `PACKETCAPTURE_NEIGHBORS_COMMAND_TIMEOUT`, `PACKETCAPTURE_NEIGHBORS_SCOPE_TIMEOUT`, `PACKETCAPTURE_NEIGHBORS_SCOPE_MIN_TIMEOUT`, `PACKETCAPTURE_NEIGHBORS_SCOPE_GAP`, `PACKETCAPTURE_NEIGHBORS_CYCLE_TIMEOUT`, `PACKETCAPTURE_NEIGHBORS_MAX`, `PACKETCAPTURE_NEIGHBORS_SELF_SCOPES`.
- Log rotation (v2.1.0+): `PACKETCAPTURE_LOG_ROTATION`, `PACKETCAPTURE_LOG_MAX_BYTES`, `PACKETCAPTURE_LOG_ROTATION_WHEN`, `PACKETCAPTURE_LOG_BACKUP_COUNT`.
- Keys: `PACKETCAPTURE_PRIVATE_KEY` or `PACKETCAPTURE_PRIVATE_KEY_FILE`.

Use the TOML names when writing configuration. Use the environment names when injecting Docker or service settings.

## MQTT broker slots

For broker `n`, the environment form is `PACKETCAPTURE_MQTT<n>_*`. Common fields are `ENABLED`, `NAME`, `SERVER`, `PORT`, `TRANSPORT`, `USE_TLS`, `TLS_VERIFY`, `USERNAME`, `PASSWORD`, `USE_AUTH_TOKEN`, `TOKEN_AUDIENCE`, `TOKEN_TTL`, `TOKEN_OWNER`, `TOKEN_EMAIL`, `TOPIC_TOKEN`, `CLIENT_ID_PREFIX`, `QOS`, `RETAIN`, `KEEPALIVE`, plus v2.1.0+ `INCLUDE_DECODED` and `NEIGHBORS` per-broker feature flags.

Supported topic placeholders:

- `{IATA}`: uppercase IATA code
- `{IATA_lower}`: lowercase IATA code
- `{PUBLIC_KEY}`: connected radio public key
- `{TOKEN}`: broker-specific or global topic token

A broker-specific topic wins over the global topic. `RAW` has no implicit default and is skipped unless configured. Per-broker topic keys: `status`, `packets`, `decoded`, `debug`, `raw`, `neighbors`. If no topic is configured, an IATA-aware default is used when a non-`LOC` IATA exists; custom brokers without IATA use classic topics; LetsMesh brokers without IATA do not receive default topics.

## Authentication

Password auth:

```toml
[broker.auth]
method = "password"
username = "mqtt-user"
password = "mqtt-password"
```

Token auth:

```toml
[broker.auth]
method = "token"
audience = "mqtt.example.com"
token_ttl = 3600
# owner = "64_HEX_CHAR_PUBLIC_KEY"
# email = "owner@example.com"
```

Per-broker `owner` and `email` (v2.1.0+) override the global `capture.owner_public_key` / `capture.owner_email` for that broker's token.

Token generation prefers on-device signing through the connected MeshCore instance. If that fails, it can use a 64-byte MeshCore private key (128 hex characters) from configuration/environment/file, subject to device and firmware support. `AUTH_TOKEN_METHOD=python` forces Python signing; `AUTH_TOKEN_METHOD=meshcore-decoder` selects the external decoder path. Never log or paste the key.

## Packet filtering and output

`PACKETCAPTURE_UPLOAD_PACKET_TYPES` accepts comma-separated numeric packet types. Known values are `0` REQ, `1` RESPONSE, `2` TXT_MSG, `3` ACK, `4` ADVERT, `5` GRP_TXT, `6` GRP_DATA, `7` ANON_REQ, `8` PATH, `9` TRACE, `10` MULTIPART, `11` CONTROL, `15` RAW_CUSTOM. Empty/unset means all packet types are uploaded; filtering affects MQTT upload, not local capture.

`--output PATH` writes packet output. `--verbose` adds JSON to normal output. `--debug` enables detailed diagnostics. `--no-mqtt` disables publishing while leaving capture active. `--neighbors-now` runs one neighbors discovery + scopes cycle immediately (v2.1.0+); add `--neighbors-exit` to quit when the cycle finishes. With `decode_payloads` enabled, each record gains a nested `decoded` object (GRP_TXT sender/text, ADVERT name/role/lat/lon, type/route labels); direct TXT_MSG payloads remain opaque to a passive observer. Log rotation (`log_rotation`, `log_max_bytes`, `log_rotation_when`, `log_backup_count`) applies when `--output` names a file.

# Deployment and troubleshooting

Source basis: `agessaman/meshcore-packet-capture` commit `c011f4e` (v2.2.0), inspected 2026-08-09. These commands are operational guidance, not proof that a target host has the required hardware or credentials.

## Manual install

For a CLI/manual run:

```bash
pipx install meshcore-packet-capture
meshcore-packet-capture --help
meshcore-packet-capture --debug --no-mqtt
```

The package requires Python 3.11+ and installs `meshcore==2.3.8` (pinned as of v2.2.0), `paho-mqtt`, BLE, serial, telemetry, and signing dependencies. A pipx install does not create a service or write `/etc` configuration.

## Managed installer

The bootstrap installer is interactive and must run with root privileges:

```bash
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/install.sh)"
```

Avoid `curl | sudo bash` for an interactive install. The bootstrap explicitly rejects stdin being consumed by the script. Download it to a temporary file if stdin is not a terminal.

By default, the installer resolves the latest published GitHub release for the payload and falls back to `main` when no release exists. Pin explicitly when needed:

```bash
sudo bash install.sh --tag v2.0.0
sudo bash install.sh --branch main
```

The installer creates `/opt/meshcore-packet-capture`, `/etc/meshcore-packet-capture/config.toml`, `/etc/meshcore-packet-capture/config.d/`, a virtual environment, and state under `/var/lib/meshcore-packet-capture`. It can select systemd, launchd, Docker, or manual mode. It also supports `python3 -m installer update` and `python3 -m installer migrate` for legacy `~/.meshcore-packet-capture` layouts.

After installation, finish the user config and confirm the installer did not report missing MQTT broker or placeholder IATA. On Linux:

```bash
sudo systemctl status meshcore-packet-capture
sudo journalctl -u meshcore-packet-capture -f
sudo systemctl restart meshcore-packet-capture
```

## User service (v2.1.0+)

For a local checkout on Linux, install a per-user systemd service that runs from the checkout's `.venv`:

```bash
./install.sh --user-service               # from the checkout root
./install.sh --user-service --repo-dir /path/to/checkout
```

Config files live in the repo itself: `.env`, `.env.local`, `config.toml`, and `config.d/*.toml` (loaded in sorted order). Manage it with user-level systemd:

```bash
systemctl --user status meshcore-packet-capture
systemctl --user restart meshcore-packet-capture
journalctl --user -u meshcore-packet-capture -f
```

Remove with `./uninstall.sh --user-service` from the same checkout; add `--remove-venv` to also delete the local `.venv`. The user-service path is distinct from the root managed install: no `/opt`, `/etc`, or root service is created.

On macOS, BLE uses a per-user LaunchAgent because Bluetooth permissions are granted to the login user. Serial/TCP can use the system LaunchDaemon:

```bash
launchctl list | grep meshcore-packet-capture
 tail -f /var/log/meshcore-packet-capture.log
```

## Docker

The published Compose file uses `ghcr.io/agessaman/meshcore-packet-capture:latest`, persists `./data` at `/app/data`, and defaults to serial. Start and inspect it with:

```bash
docker compose config
docker compose up -d
docker compose ps
docker compose logs -f meshcore-capture
```

For serial, map a stable host path from `/dev/serial/by-id/` to `/dev/ttyUSB0`. Do not default to `privileged: true` for serial. For BLE, set `privileged: true`, use `PACKETCAPTURE_CONNECTION_TYPE=ble`, optionally set `PACKETCAPTURE_BLE_ADDRESS` or `PACKETCAPTURE_BLE_DEVICE_NAME`, and try `network_mode: host` if discovery fails. Linux is the reliable container target; macOS and Windows container hardware access is limited.

Mount TOML at `/etc/meshcore-packet-capture` for non-trivial configuration. Environment variables still win over the mounted TOML. `.env.local` is legacy and lower precedence than TOML.

## NixOS

The repository includes a NixOS module under `services.meshcore-packet-capture`. Configure `connectionType`, the radio transport, `mqtt1`/`mqtt2`/additional brokers, IATA, and optional key settings, then run:

```bash
sudo nixos-rebuild switch
journalctl -u meshcore-packet-capture -f
```

The module's documentation shows LetsMesh WebSocket/TLS examples and custom password-authenticated brokers. Verify the module source against the current checkout before copying options because Nix attribute names can drift independently of the Python environment-variable names.

## Evidence-first troubleshooting

### No device connection

1. Run `meshcore-packet-capture --debug --no-mqtt` outside the service/container.
2. Confirm `PACKETCAPTURE_CONNECTION_TYPE` is one of `ble`, `serial`, or `tcp`.
3. For BLE, check Bluetooth permission, adapter visibility, address/name, `ble_pin` match, and container privileges. On Linux, BlueZ may require a first-time pairing even when a PIN is configured.
4. For serial, verify the host device exists and the service user/container sees the mapped path.
5. For TCP, verify host/port reachability and inspect SDK reconnect messages.

Do not jump to MQTT diagnosis until local device connection succeeds.

### Packets connect but no MQTT data

1. Confirm the broker's `ENABLED`, `SERVER`, and `PORT` values.
2. Check that broker numbering has no gap.
3. Confirm transport/TLS pairing: WebSockets commonly uses port 443 with TLS; raw MQTT commonly uses TCP.
4. For token auth, verify audience, token TTL, device signing capability, and private-key fallback availability.
5. Inspect resolved topic templates and IATA without exposing credentials.
6. If packet filtering is configured, confirm the numeric packet type is included.
7. If expecting a `decoded` object, verify `decode_payloads` is enabled and the target broker sets `include_decoded = true`. If expecting a neighbors snapshot, verify the broker sets `neighbors = true` and an IATA (or explicit `[broker.topics] neighbors`) exists; the cycle only runs when at least one enabled broker opts in.

The process tolerates transient disconnects, retries commands, and uses MQTT grace periods. A single reconnect warning is not proof of a permanent failure; look for the later connected/failed state.

### Service starts then exits

Run the exact runtime manually with `--debug --no-mqtt` to separate application failure from service supervision. Check Python version, installed package, permissions on the serial/BLE device, writable `data_dir`, and TOML parse errors. A service may intentionally exit after configured failure thresholds so systemd/launchd can restart it.

### Safe update or removal

Before updating or uninstalling, identify the active service/container and back up `config.d/99-user.toml`. Stop and verify the old process before removing anything. The upstream uninstaller is interactive, backs up user configuration when selected, and can remove services, container/image, install files, logs, `/etc/meshcore-packet-capture`, and `/var/lib/meshcore-packet-capture`. Do not reproduce its `rm -rf` actions casually during troubleshooting.

# Source index

This skill was built from the public repository [agessaman/meshcore-packet-capture](https://github.com/agessaman/meshcore-packet-capture), inspected at commit `c011f4e` on 2026-08-09. The checkout reported release `v2.2.0`, published 2026-07-30. Upstream is the source of truth when this skill conflicts with a newer release.

## Coverage inventory

- [x] `README.md`: scope, install modes, configuration precedence, CLI, Docker, output, topics, troubleshooting
- [x] `pyproject.toml`, `requirements.txt`: Python/runtime dependency floor (meshcore pinned `==2.3.8` as of v2.2.0) and CLI entry point
- [x] `src/meshcore_packet_capture/__main__.py`: installed command dispatch
- [x] `src/meshcore_packet_capture/packet_capture.py`: transports, retries, health checks, MQTT, topics, stats, filters, output, shutdown, neighbors CLI flags (`--neighbors-now`, `--neighbors-exit`)
- [x] `src/meshcore_packet_capture/config_loader.py`: TOML loading, deep merge, named broker merge, environment flattening, decoding/neighbors/log-rotation keys
- [x] `src/meshcore_packet_capture/auth_token.py`: device/Python/decoder signing and key format
- [x] `src/meshcore_packet_capture/enums.py`: packet and route type vocabulary
- [x] `src/meshcore_packet_capture/payload_decode.py`: GRP_TXT decryption, ADVERT parsing, structured decode fields (v2.1.0+)
- [x] `src/meshcore_packet_capture/neighbors.py`: zero-hop neighbor discovery + region-scope collection for the neighbors topic (v2.1.0+)
- [x] `config.toml.example`, `.env`: configuration surface and legacy aliases (decode/neighbors/log-rotation blocks, `ble_pin`, per-broker `include_decoded`/`neighbors`/`owner`/`email`)
- [x] `presets/*.toml`: broker preset shape and sequential broker behavior
- [x] `DOCKER.md`, `docker-compose.yml`, `Dockerfile`: container deployment and hardware access
- [x] `NIXOS.md`, `nix/`: NixOS package/module deployment
- [x] `install.sh`, `installer/`: bootstrap, release resolution, interactive install, update, migrate, `--user-service` flow
- [x] `packaging/systemd/`, `packaging/launchd/`: service supervision and platform permissions
- [x] `uninstall.sh`: backup, `--user-service` removal, and destructive cleanup boundaries
- [x] `devtools/`: BLE/network diagnostic helpers, treated as optional development tools
- [x] `tests/`: configuration, installer, CLI, packet parsing, JWT, presets, and lifecycle behavior
- [x] `.github/workflows/`: Docker, Nix, pytest, and release automation

## Reconciliation notes

- The README says the recommended meshcore dependency is `>=2.2.31`; `pyproject.toml` at v2.2.0 pins `==2.3.8` and the contact-injection shim was removed. The skill follows the pin.
- TOML is described as primary, but the actual precedence depends on whether a value came from the real process environment or a dotenv file. The skill documents the implementation's snapshot behavior.
- The README says the installer installs the latest release by default; `installer/__main__.py` and `install.sh` confirm explicit `--tag`/`--branch` overrides, plus the v2.1.0+ `--user-service` local-checkout flow.
- Older README examples mention `docker-compose`; current `DOCKER.md` uses `docker compose`. Prefer the Compose v2 form.
- `NIXOS.md` documents a bounded broker example; `config_loader.py` and tests show the Python runtime supports more than four enabled brokers. The skill follows the runtime for the general rule and treats Nix option count as module-specific.
- Upstream contains compatibility/development helpers and a large implementation file. This skill distills operation and diagnosis rather than copying source code.

## Refresh procedure

1. Fetch the current default branch and latest release with `gh`.
2. Re-read `README.md`, `pyproject.toml`, `config.toml.example`, `DOCKER.md`, `NIXOS.md`, service templates, installer entry points, config loader, CLI parser, `payload_decode.py`, and `neighbors.py`.
3. Run the upstream tests if dependencies and hardware-independent fixtures are available.
4. Update this index's commit/date and reconcile every changed command, default, version, and environment variable before changing executable guidance.