# gitrdone Agent Guide

> gitrdone is an authenticated Git smart HTTP 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 lower-level than Differ: it serves Git repos, tokens, and Git smart HTTP. Product concepts such as stems, divergences, adaptations, and app ownership belong in Differ.

## Discovery

- Agent index: [https://grd-local.differ.ac/llms.txt](https://grd-local.differ.ac/llms.txt)
- Full agent guide: [https://grd-local.differ.ac/AGENTS.md](https://grd-local.differ.ac/AGENTS.md)
- Lowercase guide alias: [https://grd-local.differ.ac/agents.md](https://grd-local.differ.ac/agents.md)
- Well-known guide alias: [https://grd-local.differ.ac/.well-known/agents.md](https://grd-local.differ.ac/.well-known/agents.md)
- Markdown sitemap: [https://grd-local.differ.ac/sitemap.md](https://grd-local.differ.ac/sitemap.md)
- XML sitemap: [https://grd-local.differ.ac/sitemap.xml](https://grd-local.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
- write: push
- readwrite: clone, fetch, pull, push

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: differ:import:imp_123:source-read-token
Idempotency-Key: differ:divergence:div_456:push-token
Idempotency-Key: differ:adaptation-run:run_789:stem-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 Differ 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 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-local.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 are internal implementation details.
- Do not assume anonymous repo access. Git access requires repo tokens.
- Do not treat Differ concepts as gitrdone concepts. gitrdone does not know stems, divergences, adaptations, apps, or logged-in product users.