# CLAUDE.md -- Guildhouse Proto

## Project Identity

Canonical protobuf definitions for all Guildhouse gRPC services.
Consumed by:
- **guildhouse-platform** (Rust/tonic-build) via git submodule
- **guildhouse-dashboard** (Python/grpcio-tools) via git submodule

## Domains

| Domain | Directory | Files | Purpose |
|--------|-----------|-------|---------|
| Quartermaster | `quartermaster/v1/` | 6 | Governance, registry, notary, credentials, capabilities, pipelines |
| Bascule | `bascule/v1/` | 4 | Session, command, gateway, ceremony |
| Workspace | `workspace/v1/` | 1 | Workspace management |
| Runner | `runner/v1/` | 2 | Pipeline execution |
| Schematic | `schematic/v1/` | 2 | Composite meta-artifacts, infrastructure offerings |
| Attestation | `attestation/v1/` | (if present) | Substrate attestation types |

## Versioning

Proto files use domain-versioned paths (e.g., `quartermaster/v1/`). Breaking changes require a new version directory (e.g., `quartermaster/v2/`).

## Build / Lint

```bash
# Lint protos (requires buf)
buf lint

# Breaking change detection
buf breaking --against '.git#branch=main'
```

CI is configured in `.forgejo/workflows/ci.yaml` (buf lint + breaking change detection).

## Related Repos

- `~/projects/guildhouse/` -- Rust services that implement these APIs
- `~/projects/guildhouse-dashboard/` -- Django dashboard that calls these APIs
- `~/projects/guildhouse-spire-plugins/` -- Go plugins (copies protos for local codegen)