# Aptarium reference

## Identity and data invariants

- Production login is verified Google OIDC only.
- Connector reads are allowlisted and read-only. Live reads execute as the viewer.
- Snapshots name the maker and capture time; there is no shared connector credential.
- Apps require authentication and viewers are never billed.

## CLI

| Task | Command form |
|---|---|
| Pair | `aptarium setup [workspace] [--agent name] [--share]` |
| Create | `aptarium init [blank|sprint-dashboard|release-tracker|weekly-report] --dir path` |
| Deploy | `aptarium deploy path --app slug --message text` |
| Inspect apps | `aptarium ls`, `aptarium open app`, `aptarium logs app` |
| Versions | `aptarium versions app`, `aptarium diff app a b`, `aptarium pull app --version n --dir path`, `aptarium rollback app n` |
| Jira | `aptarium connect jira`, `aptarium connections`, `aptarium data schema jira operation`, `aptarium data call jira operation --params json --limit n` |
| Snapshot | `aptarium snapshot app binding` |
| Share | `aptarium share app --me|--space s|--org|--user email|--guest email` |
| Revoke access | `aptarium unshare app --space|--org|--user email|--guest email` |
| Inspect access | `aptarium audience app` |

Every command accepts global `--json`. Stable CLI failures include an error
code, message, exit code, and an actionable suggestion.

## Manifest

The canonical JSON Schema is [app/v1.json](https://staging.patchbraid.info/schemas/app/v1.json).
`aptarium.json` declares title, description, tags, CSP additions, and named
bindings. A binding declares `connector`, read-only `operation`, fixed
`params`, constrained viewer `expose` fields, cache TTL, and optional
snapshot schedule. Deployed files may not contain secrets or external origins
outside the declared CSP.

## Runtime data

`aptarium.data.read(binding, { params, cursor, limit, mode })` returns
`{ columns, rows, meta }`. Preserve `meta.next_cursor` unchanged when
`meta.truncated` is true. `mode` may select `live` or `snapshot`.
`aptarium.data.provenance(binding)` reports snapshot id, as-of time, and
baker. The supplied UI helpers render connection, retry, typed error, and
provenance states without external script dependencies.

## Stable recovery codes

| Code | Recovery |
|---|---|
| `NOT_CONNECTED` | Connect the viewer's Jira account, then retry once. |
| `NO_ACCESS` | Jira or Aptarium denied this viewer; do not fall back to another user's credential. |
| `BINDING_UNDECLARED` | Add the binding to the manifest and redeploy. |
| `PARAM_INVALID` | Use the manifest's exposed parameter schema. |
| `UPSTREAM_DOWN` | Retry; a labeled snapshot may be offered when available. |
| `RATE_LIMITED` | Wait for `retry_after_seconds`. |
| `SNAPSHOT_MISSING` | A maker performs the first bake. |
| `SNAPSHOT_STALE` | The named baker reconnects and publishes a fresh snapshot. |
| `quota_exceeded` | Review Settings → Plan and usage; viewer access remains unmetered. |