# gitrdone Agent Guide

> gitrdone is an authenticated Git smart HTTP and Git LFS service with a small control API for creating backing Git repos and repo-scoped access tokens.

Use this guide when acting as an automated agent against gitrdone. gitrdone is intentionally narrow: it serves Git repos, tokens, Git smart HTTP, and Git LFS. Higher-level product concepts belong in the caller.

## Discovery

- Agent index: [https://grd.differ.ac/llms.txt](https://grd.differ.ac/llms.txt)
- Full agent guide: [https://grd.differ.ac/AGENTS.md](https://grd.differ.ac/AGENTS.md)
- Lowercase guide alias: [https://grd.differ.ac/agents.md](https://grd.differ.ac/agents.md)
- Well-known guide alias: [https://grd.differ.ac/.well-known/agents.md](https://grd.differ.ac/.well-known/agents.md)
- Markdown sitemap: [https://grd.differ.ac/sitemap.md](https://grd.differ.ac/sitemap.md)
- XML sitemap: [https://grd.differ.ac/sitemap.xml](https://grd.differ.ac/sitemap.xml)

## Authentication

Control API endpoints require an internal control bearer token. Git endpoints require repo-scoped tokens minted by the control API.

Repo tokens are capability grants, not user identity sessions. The token subject is audit context supplied by the caller. Supported repo token scopes are:

- read: clone, fetch, pull, Git LFS downloads, read diff endpoints
- write: push, Git LFS uploads
- readwrite: clone, fetch, pull, push, Git LFS upload/download, read diff endpoints

Normal Git clients should use Basic auth with username x-access-token and a repo token as the password. Do not persist repo tokens in remote URLs. Bearer auth is also accepted by Git routes for service callers.

## Reliable token creation

For POST /v1/repos/{repoID}/tokens, include Idempotency-Key when retrying or when the request is part of a durable workflow.

Use a key derived from the logical operation, not from a single HTTP attempt:

```http
Idempotency-Key: import:imp_123:source-read-token
Idempotency-Key: workflow:run_456:push-token
Idempotency-Key: release:rel_789:write-token
```

Reuse the same key only for the same repo, scope, subject, and TTL. If the same key is reused for a different token request, gitrdone returns 409 Conflict; do not blindly retry that conflict.

## Token lifecycle

List and revoke responses return token metadata only; token values are returned only at creation. Keep the token id returned by token creation if the workflow may need to revoke or audit that grant later.

Use GET /v1/repos/{repoID}/tokens to inspect token ids, scopes, subjects, expiration times, revocation times, and last-use times for a repo. Use POST /v1/repos/{repoID}/tokens/{tokenID}/revoke to revoke a repo token. Revocation is repo-scoped; do not try to revoke a token through a different repo.

Revoke tokens when a workflow is done or when a token may have leaked. If work must continue after revocation, mint a fresh token for the new logical operation.

## Agent-safe surfaces

Public discovery:

- GET /
- GET /llms.txt
- GET /.well-known/llms.txt
- GET /AGENTS.md
- GET /agents.md
- GET /.well-known/agents.md
- GET /llms-full.txt
- GET /robots.txt
- GET /sitemap.md
- GET /sitemap.xml
- GET /healthz

Control API for trusted services:

- POST /v1/repos
- GET /v1/repos/{repoID}
- POST /v1/repos/{repoID}/tokens
- GET /v1/repos/{repoID}/tokens
- POST /v1/repos/{repoID}/tokens/{tokenID}/revoke
- POST /v1/repos/{repoID}/archive

Git smart HTTP for normal Git clients:

- GET /git/repos/{repoID}.git/info/refs?service=git-upload-pack
- POST /git/repos/{repoID}.git/git-upload-pack
- GET /git/repos/{repoID}.git/info/refs?service=git-receive-pack
- POST /git/repos/{repoID}.git/git-receive-pack

Git LFS for normal git-lfs clients:

- POST /git/repos/{repoID}.git/info/lfs/objects/batch
- PUT /git/repos/{repoID}.git/info/lfs/objects/{oid}
- GET /git/repos/{repoID}.git/info/lfs/objects/{oid}
- POST /git/repos/{repoID}.git/info/lfs/locks/verify

Git LFS lock verification returns an empty conflict set. gitrdone does not provide collaborative LFS locking.

Read-only diff endpoints for service callers:

- GET /git/repos/{repoID}.git/show/{sha}.diff
- GET /git/repos/{repoID}.git/compare/{base}..{head}.diff
- GET /git/repos/{repoID}.git/compare/{base}...{head}.diff

Diff revisions must be lowercase hex object IDs, full or abbreviated from 7 to 64 characters. Diff responses larger than 8 MiB return 413 Request Entity Too Large.

## Git command use

Prefer ordinary Git commands over handcrafted protocol requests:

```bash
git clone <gitUrl>
git fetch
git pull
git push origin main
```

The canonical Git remote URL shape is:

```text
https://grd.differ.ac/git/repos/{repoID}.git
```

repoID is the external control ID, for example repo_00000000-0000-4000-8000-000000000000.

## Do not hit

- Do not use namespace/name Git routes. They are not canonical.
- Do not scrape storage paths. Bare repo paths and LFS object paths are internal implementation details.
- Do not assume anonymous repo access. Git access requires repo tokens.
- Do not treat caller product concepts as gitrdone concepts. gitrdone does not know application workflows, tenants, or logged-in product users.