# Software Atlas Agent Guide

Software Atlas measures the source footprint of a package and its transitive runtime
dependencies. This guide is for coding agents and automated clients.

Base URL: `https://software-atlas.aisloppy.com`

## Quick start

Create an account with a strong, unique password. Store the password and returned
token securely; never commit either one.

```bash
BASE_URL=https://software-atlas.aisloppy.com
EMAIL=agent@example.com
PASSWORD=$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')

curl --fail-with-body --max-time 15 \
  -X POST https://authreturn.com/api/apps/software-atlas/signup \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}"
```

The response contains a `token`. Send it on every authenticated request:

```text
Authorization: Bearer <token>
```

If the account already exists, obtain a fresh token with:

```bash
curl --fail-with-body --max-time 15 \
  -X POST https://authreturn.com/api/apps/software-atlas/login \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}"
```

Signup and login return `200` with:

```json
{"success": true, "token": "<jwt>", "user_id": "<id>", "email": "agent@example.com"}
```

Tokens expire. On `401`, log in again and retry the request once. Signup availability
is controlled by the service; a rejected signup returns a concrete JSON `error`.

## Start a survey

```bash
curl --fail-with-body --max-time 15 \
  -X POST "$BASE_URL/api/atlas" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'X-Software-Atlas-Client: coding-agent' \
  -H 'Content-Type: application/json' \
  -d '{"system":"pypi","package":"requests"}'
```

Supported systems are `npm`, `pypi`, `cargo`, `go`, `maven`, `rubygems`, and
`nuget`. `version` is optional. A successful request returns `202`:

```json
{"id": "<job_id>"}
```

Closures over 500 packages are rejected instead of silently truncated.

Coding agents should send `X-Software-Atlas-Client: coding-agent` when starting a
survey. Software Atlas records survey starts and this client category in Grid Glance;
it does not send package names, tokens, passwords, or request bodies to analytics.

## Poll for completion

```bash
curl --fail-with-body --max-time 15 \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/atlas/$JOB_ID"
```

Poll every few seconds and impose an overall deadline appropriate for your caller;
large surveys can take minutes. Status is one of `queued`, `resolving`, `counting`,
`done`, or `error`. Stop polling on `done` or `error` and surface the returned
`error` unchanged.

Each status response contains:

```json
{
  "status": "queued|resolving|counting|done|error",
  "error": null,
  "done": 0,
  "total": 0,
  "result": null
}
```

On `done`, `result` contains:

- `root`: the requested package.
- `totals`: `closure_code`, `self_code`, `packages`, `unique_repos`, and
  `counted_repos`.
- `repos`: counted source repositories and their measurements.
- `uncounted`: packages grouped into `no_repo`, `non_github`, and `count_errors`.
- `nodes` and `edges`: the resolved dependency graph.
- `resolution`: the resolution method used.

## Measurement boundary

Surveys include declared runtime dependencies, excluding the language runtime and
standard library. Each unique source repository is counted once at its current
default-branch HEAD, even when several packages share it. Data and documentation
formats such as JSON, YAML, Markdown, and reStructuredText are excluded from code
totals.

Packages that cannot be measured remain in `uncounted`, so totals are a documented
floor rather than an estimate of missing code. When a resolved dependency graph is
unavailable, Software Atlas may follow declared requirements by package name;
`result.resolution` identifies the method used.

## Other authenticated endpoints

- `GET /api/atlases` returns recent surveys for the authenticated service.
- `GET /api/depsdev-check?system=<system>&package=<name>` reports whether dependency
  metadata and a resolved graph are available.
- `GET /api/repos/<owner>/<repo>` returns cached aggregate, language, file
  classification, and measurement-time evidence for an already-counted public repo.

Machine clients with `X-API-Key` may measure a repository with `POST /api/repos`
and `{"full_name":"owner/repo"}`. Existing evidence is returned immediately with
`cache_status: "hit"`; send `{"full_name":"owner/repo","refresh":true}` only when
a fresh default-branch clone is required. The response includes numeric `code` LOC.

## Errors and operational rules

- `400`: invalid or missing input; read the JSON `error`.
- `401`: missing or expired credentials; log in and retry once.
- `404`: job, package, or cached repository not found.
- `500`: survey or upstream failure; preserve the JSON `error` for the operator.

Every network call needs an explicit timeout. Every polling loop needs an overall
deadline and must terminate visibly on success, error, or timeout. Do not log tokens,
passwords, or complete authenticated request headers.

## Public utility endpoints

- `GET /api/health`
- `GET /api/version`
- `GET /agent-guide.md`
- `GET /agent-guide`