# AGENTS.md

## Purpose

This repository hosts a small self-hosted scratch service written in Go.

Key product constraints:
- All routes are unauthenticated by design.
- One upload creates one scratch.
- For multiple files, users must upload a single archive file.
- Scratch data is stored gzip-compressed on disk transparently.

## Project layout

- `cmd/scratchbox`: service entrypoint
- `internal/config`: config loading and validation
- `internal/http`: HTTP handlers and middleware
- `internal/storage`: filesystem storage and metadata index
- `internal/cleanup`: expiration cleanup worker
- `web/templates`, `web/static`: UI assets

## API routes

- `POST /api/scratch`
- `GET /api/scratch/{id}`
- `GET /s/{id}`
- `GET /api/raw/{id}`

## Build and test

Use `make help` as the source of truth for available build/test targets and descriptions.
Always build and test via make unless it doesn't include targets for that.
Also in the event there is a test without race checking and one with do both.
Otherwise just whats available.
To verify your changes you must run tests and do a build.

## Coding conventions

- Keep changes minimal and focused.
- Backward compatibility is not a concern unless explicitly requested.
- Do not add compatibility shims, fallback paths, legacy aliases, or dual behavior unless explicitly requested.
- Preserve unauthenticated behavior unless explicitly requested.
- Keep limits/operator controls configurable via config.
- Maintain write-route protections (allowlist and rate limiting).
- Keep storage behavior transparent for clients (compression is internal).
- Add or update tests for behavior changes.

## Cobra CLI conventions

- Keep `cmd/scratchbox/main.go` focused on `main()` and root command wiring.
- Put each Cobra subcommand in its own file (for example `cmd/scratchbox/server.go`).
- Start the service through the explicit subcommand (`scratchbox server`), not from the root command directly.
- Validate command arguments with Cobra arg validators (for example `cobra.NoArgs`) where applicable.