setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Setup — Stand Up the Fleet Agent

Walk the user through a working install one step at a time, pausing to confirm each integration is live before moving on. Don't dump the whole list at once.

The agent pulls from **Motive (GoMotive)** telematics and sends/receives as a **shared mailbox** via a Microsoft Entra app. Both are required; two companion inputs (employee roster, project index) are optional.

## Step 0 — Prerequisites

- **Python 3.12+** and the deps: `pip install -r requirements.txt`.
- **The Tesseract binary** for OCR of scanned invoices/inspections (the `pytesseract` package needs it): `winget install --id UB-Mannheim.TesseractOCR` (Windows) / `apt-get install tesseract-ocr` / `brew install tesseract`. Without it, ingest still runs but queues scanned docs for manual handling.
- **A Motive (GoMotive) account** with an admin **read** API key.
- **A Microsoft 365 tenant** where you (or an admin) can create an app registration, and a **shared mailbox** the agent will act as (e.g. `fleet@yourco.com`).

## Step 1 — Config + secrets

```bash
cp config.example.toml config.toml         # non-secret runtime values
cp .env.example ~/.fleet-agent/.env        # secrets (or set FLEET_ENV)
cp brand/brand.example.yml brand/brand.yml
```

Fill in `config.toml`: `[paths].home`/`publish_dir`, `[email].mailbox` + `recipients`, `[site]` yard coordinates, `[inspections]` SharePoint IDs (Step 4). Fill in `.env`: `MOTIVE_API_KEY`, `FLEETAGENT_TENANT_ID/CLIENT_ID/CLIENT_SECRET`. Leave the optional `[paths].nance_users`/`kbnt_projects` commented unless you have those inputs.

## Step 2 — Motive check

```bash
python scripts/check_motive.py     # confirms the Motive key + lists a few assets
```

## Step 3 — Entra app + mailbox sign-in

Create an Entra app with delegated `Mail.ReadWrite` + `Mail.Send` (and application access as needed), admin-consent, and put the IDs in `.env`. Then seed the mailbox token cache:

```bash
python scripts/fleet_signin.py     # device code — sign in AS the mailbox (config [email].mailbox)
python scripts/check_fleet_auth.py # verifies the signed-in identity matches the configured mailbox
```

## Step 4 — Inspections list (optional, if you use SharePoint pre-use inspections)

Find the site + list via Graph (`GET /sites?search=...`, then `/sites/{id}/lists`) and put the IDs in `config.toml [inspections]`.

## Step 5 — Brand

Set `brand/brand.yml` (`meta.name`, primary/secondary colors); drop your logo at `brand/assets/logo.svg`.

## Step 6 — First dry run

```bash
python scripts/run_pipeline.py             # stage-only, no email (safe)
python scripts/run_pipeline.py --report    # also build the reports locally
```
Review the output, then go live with `/fleet-report` (pipeline + send) once it looks right.

## Step 7 — The rhythm (hand off to the other skills)

- `/fleet-pipeline` — the daily run (no email).
- `/fleet-report` — the weekly run + send.
- `/fleet-publish` — publish per-asset records to the shared folders.
- `/fleet-health` — Motive + mailbox auth checks.

## Safety notes to surface

- Motive access is **read-only**; the agent never writes to Motive.
- Secrets live only in `.env` (gitignored, outside the repo); `config.toml` is gitignored too. Never commit either.
- `paths.guard_live()` blocks live side-effects unless run from the configured `[paths].home` (`FLEET_ALLOW_ANY=1` overrides for a sandbox).
- Always dry-run (`run_pipeline.py` without `--live`) before the first live send.

From taymac/fleet-agent, MIT.

More from taymac/fleet-agent