# AGENTS.md — PackOps agent contract

PackOps (https://workshop.ashlar-vellum.com) is AlphaCorr's packaging operations platform: CAD/design
file unlock and conversion (CimPACK, ArtiosCAD, Adobe Illustrator, Impact),
3D fold visualization, calibration-grade photo measurement, jobs, orders,
and supplier sourcing. Agents are first-class clients here — the same
capabilities humans use in the portal are exposed over MCP and a bearer
REST API.

This file is the contract: how to connect, what you may do, and the rules
that keep your results correct.

## Capabilities

- **MCP server** at `https://workshop.ashlar-vellum.com/mcp` — Streamable HTTP transport, stateless,
  JSON responses. Tool list (live, generated from the running server):
  `https://workshop.ashlar-vellum.com/.well-known/mcp-server-card.json`. Tools cover account/org
  resolution, the work queue (inbox/outbox), scene intake, CRR design
  resolution, calibration targets (list/export/import), uploads with
  signed downloads, content hashing, jobs and artifacts, orders, files,
  and search.
- **REST integration API** under `https://workshop.ashlar-vellum.com/api/integrations/` — OpenAPI:
  `https://workshop.ashlar-vellum.com/openapi.json` (curated public surface; internal portal routes
  are deliberately undocumented).

## Connect — interactive agents (you act as your human)

1. Add an MCP connector pointing at `https://workshop.ashlar-vellum.com/mcp`, or better, a per-org
   connector URL `https://workshop.ashlar-vellum.com/mcp/o/{org_uuid}` (see Rules → Organizations).
2. Standard MCP OAuth discovery applies: an unauthenticated request gets
   `401` + `WWW-Authenticate` pointing at the RFC 9728 resource metadata
   (`https://workshop.ashlar-vellum.com/.well-known/oauth-protected-resource/mcp`), which names the
   authorization server. Authorization-code + PKCE (S256). Dynamic Client
   Registration (RFC 7591) is supported for hosted Claude surfaces;
   Claude Code and Claude Desktop connect with the documented public
   client. You log in as your human and act with their org permissions.
3. Call `get_account` first. It returns who you are, your organizations,
   and a paste-ready per-org connector URL for each.

## Connect — machine-to-machine

`client_credentials` against the same authorization server with an
AlphaCorr-issued scoped client. M2M clients are tenant-locked to one
organization and carry explicit scopes (account, queue, intake, resolve,
jobs, orders, uploads, calibration). Request one via your AlphaCorr
contact.

## Rules

1. **Organizations are always explicit.** There is no implicit or default
   org. Bind one of three ways: a per-org connector URL (hard-locked — a
   divergent per-call org is refused), a per-call `org_uuid` parameter,
   or one account per org. If you omit the org where one is required, the
   error names your options — read it.
2. **Values travel with units.** Every dimensional value this API emits
   (lengths, weights, grid spans) carries its unit alongside the number.
   Preserve the pair; never strip a unit and assume a canonical one
   ("the Mars rule").
3. **Signed download URLs expire** (minutes, not hours). Fetch promptly;
   re-request rather than caching the URL.
4. **Inline binary uploads are capped** (50 MB per photo). Larger
   transfers belong on the upload endpoints, not inline tool arguments.
5. **Demo organizations are read-only.** Writes there are refused by
   design — switch to a real org rather than retrying.
6. **Errors are informational, not terminal.** Tool errors state what was
   wrong and usually how to fix it (missing org → your org menu; bad
   scope → the scope name). Correct and retry; don't loop blindly.
7. **Be a polite client.** No unauthenticated endpoint scraping; the
   discovery surfaces below tell you everything that's public. Honor
   `robots.txt` when crawling.

## Discovery surfaces

| Surface | Path |
|---|---|
| MCP server card | `/.well-known/mcp-server-card.json` (alias `/agents.json`) |
| OAuth protected-resource metadata (RFC 9728) | `/.well-known/oauth-protected-resource` (+`/mcp`, +`/mcp/o/{org_uuid}`) |
| OAuth authorization-server metadata (RFC 8414) | `/.well-known/oauth-authorization-server` |
| Curated OpenAPI | `/openapi.json` |
| This contract | `/AGENTS.md` (alias `/.well-known/agent-rules`) |
| LLM index | `/llms.txt` |
| Sitemap | `/sitemap.xml` |

## Ecosystem

- **Feeder portals** (file intake, same account, SSO):
  [cim.alphacorr.com](https://cim.alphacorr.com) (CimPACK),
  [ard.alphacorr.com](https://ard.alphacorr.com) (ArtiosCAD),
  [ipd.alphacorr.com](https://ipd.alphacorr.com) (Impact).
- **Desktop:** Rules-3D (AlphaCorr's CAD application) is gaining an SDK
  and MCP integration; further desktop applications will follow the same
  agents-first pattern.
- **Mobile:** the PackOps mobile app consumes the same bearer REST API.

## For humans

A signed-in walkthrough for connecting Claude (and other MCP clients)
lives at `https://workshop.ashlar-vellum.com/connect/claude`. Integration principles:
`https://workshop.ashlar-vellum.com/principles/integrations`.