# ArcSync — Agent Instructions

ArcSync generates interactive architecture diagrams from infrastructure-as-code (Terraform, CloudFormation).

## What You Can Do

- **Generate diagrams**: POST to `/graphs/generate` with a Git repo URL to create architecture diagrams
- **Upload graph data**: POST to `/graphs/ingest` to upload pre-parsed graph data
- **Browse public diagrams**: GET `/gallery` for public examples (no auth needed)
- **Retrieve graph data**: GET `/graphs/{id}` for full graph JSON
- **Export as Mermaid**: Use the CLI (`npx @auto-arch-diagram/cli`) for Mermaid markdown output

## API Base URL

`https://api.arcsync.dev`

## Authentication

Authenticated endpoints require a Bearer token from Auth0. Public gallery endpoints (`/gallery`, `/gallery/{id}`) require no auth.

## Key Endpoints for Agents

| Action | Method | Path | Auth |
|--------|--------|------|------|
| Generate diagram from repo | POST | /graphs/generate | Yes |
| List public diagrams | GET | /gallery | No |
| Get public diagram | GET | /gallery/{id} | No |
| Get user's diagrams | GET | /graphs | Yes |
| Get diagram data | GET | /graphs/{id} | Yes |

## CLI for Local Use

```bash
npx @auto-arch-diagram/cli ./path/to/terraform
```

Outputs Mermaid markdown to stdout. No API key or auth required.

## GitHub Action

```yaml
- uses: neilvanlandingham/arcsync@v1
  with:
    path: ./infrastructure
```

## Input Format Notes

- Terraform: Reads `.tf` HCL source files
- CloudFormation: Reads JSON/YAML templates, including CDK `cdk.out/` synthesized stacks
- Multi-stack CloudFormation is supported (cross-stack references are resolved)

## Limitations

- Private Git repos require auth tokens in the repo URL
- Maximum repo clone size: approximately 500 MB
- Graph generation is async — poll `/graphs/{id}/status` or listen on WebSocket