AGENTS.md git:20260612.b6ce5a3A

Immutable. This exact content is served forever at /api/v1/blob/ebbbd69278162178.

# AGENTS.md - msp-skills

Instructions for AI agents working in this repository. Read this before making
changes; see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the human-facing version.

## What this repo is

A monorepo of MSP vendor connectors. Each `skills/<slug>/cli` is a Go CLI + MCP
server **generated by [cli-printing-press](https://github.com/mvanhorn/cli-printing-press)**
and then carries connector-specific edits. The press is upstream and refreshes
independently; we pull new binaries and **reprint** connectors over time.

## Before you reprint or re-onboard a connector (READ THIS)

A reprint regenerates the `DO NOT EDIT` files under `skills/<slug>/cli` and can
**silently clobber** a hand-fix - the build and tests stay green while the
live-API behavior the fix encoded is gone (this is how the axcient `id_`
primary-key fallback got reverted; see [`docs/reprint-survival.md`](docs/reprint-survival.md)).

**Whenever you regenerate, reprint, re-onboard (msp-skills-publish UPDATE), or
bulk-overwrite a connector's `cli/` tree, you MUST:**

1. **Before** generating, read the connector's recorded hand-fixes so you know
   what to preserve:

   ```bash
   python3 tools/maintainer/check_handfixes.py --brief --slug <slug>
   ```

   Preserve every entry it lists (3-way merge, don't blind-overwrite). For a
   targeted fix, prefer a surgical change over a full reprint.

2. **After** generating, prove nothing regressed:

   ```bash
   python3 tools/maintainer/check_handfixes.py --slug <slug>
   ```

   If it fails, restore the missing hand-fix (the failure names the file +
   marker) before committing. CI runs this same gate per-skill and will block
   the merge otherwise.

3. **When you add a new hand-edit to a generated file**, record it in
   `skills/<slug>/handfixes.json` in the same change, or it will be unprotected
   on the next reprint. Schema + rationale: [`docs/reprint-survival.md`](docs/reprint-survival.md).
   Prefer encoding the behavior in the spec (e.g. `x-resource-id`) when the
   press supports it - that survives by construction.

Find connectors whose hand-fixes are not yet recorded:

```bash
python3 tools/maintainer/check_handfixes.py --discover
```

## General

- Sign commits (`git commit -s`); no em-dashes in committed files; run
  `tools/maintainer/verify_all.sh <slug>` before pushing. See `CONTRIBUTING.md`.