Captures the non-obvious things an agent will hit working on this
submodule:
- Wire-format quirks (view_kind/bucket_configuration_mode are JSON
strings; Task.BucketID is always 0 in GET — use ?expand=buckets and
CurrentBucketID; POST /tasks doesn't move buckets, use the dedicated
bucket-tasks endpoint; bot creation is at /user/bots; APIToken
expires_at is required, use FarFuture for "no expiry").
- Permission discovery via /routes (group names are path-derived; use
PermissionsForBot at runtime instead of hard-coding).
- OAuth shape (PKCE/S256 mandatory, no client registration, JSON-only
token exchange, loopback redirect via 127.0.0.1:0, Shutdown uses
context.WithoutCancel to drain on outer cancel).
- Credential chain order + per-test HOME/XDG override.
- Identifier validation (runelength only) + base-36 timestamp suffix
trick for unique e2e identifiers.
- mage Aliases map (without it, `mage test` rejects the namespace).
- License-header enforcement via local .golangci.yml + code-header-
template.txt copy.
- Things to actively avoid: bare exec.Command, committing the built
binary, stdout from `prime` outside a configured workspace.
CLAUDE.md is a symlink to AGENTS.md so Claude Code picks it up via
either name.
Tink bot