interface:
  display_name: "Use Buf"
  short_description: "Manage, validate, and generate Protobuf with Buf"
  default_prompt: "Use $use-buf to configure and validate this Buf workspace."

# Buf Commands and Troubleshooting

## Required Checks

Run from the configured workspace root:

```sh
buf lint
buf generate
buf breaking --against '.git#branch=main'
```

Also use:

```sh
buf format --diff
buf build
buf dep graph --format json
git diff --exit-code
git status --short
```

If generation uses domain templates, run every affected template with `buf generate --template <template>`.
Use both Git commands because `git diff` alone does not report newly generated untracked files.

## Missing Import or Type

1. Confirm the import path spelling and module source roots.
2. Confirm the dependency exists in `buf.yaml`.
3. Inspect `buf.lock` and `buf dep graph --format json`.
4. Run `buf dep update` when dependency state is stale or intentionally changed.
5. Run `buf build` for compiler diagnostics.
6. Export the pinned dependency with `buf export` and inspect its files rather than searching an OS cache path.

## Generation Failure

1. Inspect `buf.gen*.yaml` execution type, version, revision, output, options, and strategy.
2. Confirm local executables exist and are executable, or confirm BSR connectivity/authentication for remote plugins.
3. Run `buf generate --debug` when normal stderr lacks enough detail.
4. Check for two plugins writing the same file inconsistently.
5. Check generated imports/package paths against `go_package`, managed mode, Python module paths, and TypeScript options.
6. Invoke `$use-buf-plugins` for plugin acquisition, OCI wrappers, offline operation, or rate limits.

## Breaking Changes

Run the check even for intentional pre-release breaks. Distinguish:

- accidental incompatible changes that must be fixed;
- approved experimental/unreleased breaks that require coordinated regeneration and data rebuilding;
- released incompatibilities that require a new API version.

Do not weaken global breaking rules merely to pass one change. Scope an exception only when repository policy explicitly permits it and document why.

## Dependency Hygiene

Use `buf dep prune` only after reviewing imports and generated needs. After any dependency mutation, rerun lint, build, generate, breaking checks, and target-language validation.

Official references:

- https://buf.build/docs/cli/
- https://buf.build/docs/configuration/v2/buf-yaml/
- https://buf.build/docs/configuration/v2/buf-gen-yaml/
- https://buf.build/docs/bsr/

# Buf Configuration

## Discover the Workspace

Search before editing:

```sh
rg --files -g 'buf.yaml' -g 'buf.lock' -g 'buf.gen*.yaml'
buf --version
```

Inspect root-level and API-directory configurations, generation scripts, CI, and tool pins. Determine whether the repository uses one workspace or several independent modules.

## `buf.yaml`

Use `buf.yaml` to declare:

- configuration version;
- module source paths and optional BSR module names;
- BSR schema dependencies;
- lint rules/exceptions;
- breaking-change rules/exceptions;
- policies and Buf check plugins where supported.

`buf.yaml` check plugins extend lint/breaking behavior. They are not `protoc-gen-*` code generators.

Prefer maintained BSR dependencies. Common examples include:

```yaml
deps:
  - buf.build/googleapis/googleapis
  - buf.build/protocolbuffers/wellknowntypes
  - buf.build/bufbuild/protovalidate
  - buf.build/grpc-ecosystem/grpc-gateway
```

Use only dependencies actually imported by the workspace.

## `buf.gen.yaml`

Use `buf.gen.yaml` for code generation:

```yaml
version: v2
inputs:
  - directory: proto
plugins:
  - remote: buf.build/protocolbuffers/go:<version>
    revision: <revision>
    out: gen/go
    opt:
      - paths=source_relative
```

Each plugin selects exactly one execution type: `remote`, `local`, or `protoc_builtin`. Configure `out`, `opt`, `strategy`, input/type filters, and import inclusion according to the plugin contract.

Use the default filename for the ordinary complete generation pipeline. Create `buf.gen.<domain>.yaml` only when one repository intentionally separates outputs such as server SDKs, web SDKs, documentation, or offline generation. Invoke it explicitly:

```sh
buf generate --template buf.gen.web.yaml
```

Do not create many templates merely to avoid understanding one configuration.

## Dependencies and Lock State

After changing `deps`:

```sh
buf dep update
buf dep graph --format json
git diff -- buf.yaml buf.lock
```

Never hand-edit `buf.lock`. Treat unexpected commit/digest movement as a dependency change that requires review.

To inspect a dependency schema without relying on cache internals:

```sh
export_dir="$(mktemp -d)"
buf export buf.build/<owner>/<module>:<pinned-ref> \
  --path path/inside/module.proto \
  --output "$export_dir"
```

Clean up `export_dir` after inspection.

## Generated Output Paths

Keep generated paths aligned with Protobuf import/package paths and language conventions. Use `paths=source_relative`, managed mode, or language-specific module options only after inspecting existing consumers. Do not flatten or relocate output without updating imports, packaging, CI, and downstream clients intentionally.