atgc {version}: notes for agents

Tangled
  Code lives on a knot; pull requests and issues are records in their
  author's PDS. Reads are public. A write needs an atproto session; a
  branch push needs an SSH key.

Access
    atgc doctor local --account <did>  # session, key and checkout
    git push --dry-run origin HEAD     # the only real branch-access check
  Any failure there -- permission, credentials or transport -- means no
  branch push; use --patch-only for pr/stack create. A registered key is
  not a push: an HTTPS origin never uses the SSH key.
  No session: `atgc auth login <did>`, interactively (it waits for didbot
  approval; do not pipe it). With several accounts, pass --account or
  ATGC_ACCOUNT; repo configure needs it too.
  Register a key with `atgc key add <key.pub>` (name it if several exist);
  `atgc repo configure --account <did>` pins it in this checkout.

Pull requests
  A PR is a record of rounds; each round is a patch. Pushing never
  appends a round: `pr resubmit` does. `pr create` pushes and takes the
  patch from the knot; --patch-only skips the push and records no source.
  `pr resubmit` follows the PR's shape; its push leases the last round's
  head, so never push by hand first or --force past a refusal blind.
  Check out the branch the PR's commits came from before appending a round.
  The first commit's subject and body (minus trailers) are the default
  title and description.
    atgc pr create [--patch-only]
    atgc pr resubmit 23
    atgc pr edit 23
    atgc pr diff 23 --interdiff
    atgc pr checks 23 --json   # CI for the latest round; exits 0
    atgc pr close 23

Change-ids
  Stacks match pulls to commits by a Change-Id trailer. `atgc repo
  configure` installs the hook; `atgc doctor local` says whether commits
  carry one. Existing commits need `stack create --add-change-ids`.
  Amend with `git commit --amend --no-edit`; never combine it with `-m`:
  `-m` wins, the hook stamps a new id, and the stack stops matching.

Stacks
  One PR holds as many commits as its change needs; stack only when the
  branch holds separate changes that must land in order. Mark where each
  PR ends; unmarked, one PR per commit (over three, create asks first).
  Never git rebase a stack: it strands the marks. `stack sync` is for a
  stack with a source; for patch-only, `stack resubmit <PULL>` reconciles.
  Pulls opened one at a time can be joined with `stack link`.
    atgc stack mark HEAD~3
    atgc stack create [--patch-only] [--per-commit]
    atgc stack sync
    atgc stack resubmit
    atgc stack merge

Patch-only stacks
  No key means no source on the records. Address any member by at-uri
  (keep the at-uris create prints) and walk dependentOn from there.
  Numbers arrive late; at-uri and record key always resolve. A stack is
  one account's records.
  A number from before a resubmit can 404. A member with no number, or
  with a stale link in tangled.org's chain, is an index miss: `pr touch`
  re-puts that member unchanged, so the appview sees a fresh event. Only
  the record's author can touch it; it needs no body edit and no round.
    atgc pr touch <record key>
    atgc stack view <PULL>
    atgc stack resubmit <PULL>
    atgc stack merge <PULL>
    atgc stack close <PULL>

Reporting
  atgc is pre-1.0; its services are alpha. File defects with --agent,
  which marks the issue and attaches version, platform, git and PDS host.
    atgc report bug --agent --title '...' --body 'what you ran and saw'