V3_REFERENCE = """\
# IBM Storage Scale (GPFS) management REST API — v3 reference

Compiled from IBM Storage Scale documentation 5.2.3 / 6.0.0. The native REST
API is served by the Storage Scale GUI node.

## Connection facts
- Base path: `/scalemgmt/v3`
- Default GUI port: 443 (containerised CNSA) or 46443 (native install)
- Protocol: HTTPS only
- Auth: HTTP Basic, against a Storage Scale GUI user with an admin role
- OpenAPI: live spec is at `/openapi/` on the GUI node (interactive Swagger UI)
- v3 is the current native REST API; v2 is still served on most clusters for
  backwards compatibility but new endpoints are only added under v3

## Common endpoints (non-exhaustive)

### Cluster & nodes
- `GET    /clusters`                      List local cluster info (use `?view=BASIC` for a compact summary)
- `GET    /cluster`                       Cluster configuration (legacy alias)
- `POST   /clusters/remote`               Register an owning cluster as a remote
- `GET    /nodes`                         List all nodes
- `GET    /nodes/{name}`                  Node details
- `DELETE /nodes/{name}`                  Remove a node (destructive)
- `GET    /nodeclasses`                   List node classes

### NSDs & pools
- `GET    /nsds`                          List all network-shared disks
- `GET    /nsds/{nsd}`                    NSD details
- `GET    /filesystems/{fs}/storagepools` Storage pools for a filesystem

### Filesystems
- `GET    /filesystems`                   List all filesystems
- `POST   /filesystems`                   Create a filesystem
- `GET    /filesystems/{fs}`              Filesystem detail (`?fields=mount` for mount state)
- `DELETE /filesystems/{fs}`              Delete a filesystem (destructive)
- `PUT    /filesystems/{fs}`              Modify a filesystem

### Filesets
- `GET    /filesystems/{fs}/filesets`                          List filesets
- `POST   /filesystems/{fs}/filesets`                          Create a fileset
- `GET    /filesystems/{fs}/filesets/{fileset}`                Fileset detail
- `PUT    /filesystems/{fs}/filesets/{fileset}`                Modify a fileset
- `DELETE /filesystems/{fs}/filesets/{fileset}`                Delete (destructive)
- `POST   /filesystems/{fs}/filesets/{fileset}:link`           Link a fileset to a path
- `POST   /filesystems/{fs}/filesets/{fileset}:unlink`         Unlink a fileset

### Snapshots
- `GET    /filesystems/{fs}/snapshots`                                       List global snapshots
- `POST   /filesystems/{fs}/snapshots`                                       Create a global snapshot
- `DELETE /filesystems/{fs}/snapshots/{snap}`                                Delete a global snapshot
- `GET    /filesystems/{fs}/filesets/{fileset}/snapshots`                    List fileset snapshots
- `POST   /filesystems/{fs}/filesets/{fileset}/snapshots`                    Create a fileset snapshot
- `DELETE /filesystems/{fs}/filesets/{fileset}/snapshots/{snap}`             Delete a fileset snapshot
- `POST   /filesystems/{fs}/filesets/snapshots:batchDelete`                  Batch-delete fileset snapshots

### Quotas
- `GET    /filesystems/{fs}/quotas`                  List quotas on a filesystem
- `PUT    /filesystems/{fs}/quotas`                  Set/modify quotas
- `GET    /filesystems/{fs}/quotamanagement`         Quota management state
- `GET    /filesystems/{fs}/quotadefaults`           Default quotas

### Policies & rules
- `GET    /filesystems/{fs}/policies`                Active policy
- `PUT    /filesystems/{fs}/policies`                Install / replace policy
- `GET    /filesystems/{fs}/policyrules`             Inspect rules

### Jobs (async operations)
- `GET    /jobs`                           List jobs
- `GET    /jobs/{jobId}`                   Poll a job (mutating endpoints return a jobId)

### Performance monitoring
- `GET    /perfmon/data`                   Query perfmon sensors
- `GET    /perfmon/sensors`                List configured sensors

### Auth / config
- `GET    /info`                           Product info / API version
- `GET    /config`                         GUI/cluster config

## Conventions
- Async-by-default: most `POST/PUT/DELETE` calls return `202 Accepted` with a
  `jobs[0].jobId`. Poll `/jobs/{jobId}` until the status is `COMPLETED` or
  `FAILED`. Don't assume a mutation has taken effect until the job is done.
- Many GETs accept `?fields=<csv>` to narrow the response payload.
- Collection endpoints generally accept `?filter=<expr>` for server-side
  filtering — when in doubt, fetch the collection and filter client-side.
- A colon segment like `:link` / `:unlink` / `:batchDelete` denotes a custom
  verb on a sub-resource; treat the whole thing as one path segment.

## Behaviour rules for the agent
- Use the OpenAPI spec at `/openapi/` (HTML) or `/openapi.json` if the user
  reports an endpoint that isn't listed here — it's the source of truth for
  the specific cluster version.
- If a v3 endpoint 404s, retry once at the v2 equivalent before declaring
  failure (some sites haven't upgraded the GUI yet).
- For any mutating call: state the plan in one sentence, wait for the harness
  confirmation, then poll the returned jobId.
"""