Regenerating artifacts

Audience: contributors changing error codes, CLI flags, the RPC proto, or the vendored admin-UI bundle.

Aperture keeps three kinds of generated output committed in the repo. None of them is regenerated by CI on the build path, so keeping them fresh is a manual step you own. This page is the checklist for when each one goes stale.

⚠️ There is no CI drift gate on the generated reference docs. The error-code table and CLI reference are regenerated on demand with make docs-gen. Nothing in CI fails if you forget. If you change an error code or a CLI flag and do not run make docs-gen, the published book silently goes stale. This is an accepted risk — the mitigation is you, the contributor. Make it a habit.

make docs-gen — generated reference pages

Regenerates the committed reference pages under docs/src/reference/ from the Go source:

make docs-gen

It emits two files:

You must run make docs-gen and commit the result whenever you:

• add, remove, or reword an error code, its Message, or its Fixups in errors/codes.go; or
• change the CLI — add/remove a command, flag, alias, or usage string in internal/cli/.

Then rebuild the book to confirm it is clean:

make docs-gen
make docs        # mdbook build docs — must succeed with zero errors

Commit the regenerated error-codes.md / cli.md in the same PR as the code change. Because there is no drift gate, a reviewer cannot rely on CI to catch a missed regeneration — call it out in your PR description if in doubt.

The RPC reference (docs/src/reference / the RPC surface pages) is hand-authored over internal/wire/rpc/service.proto. There is no generator for it and its drift risk is likewise accepted — update it by hand when the proto changes.

make proto — Twirp / protobuf code

The RPC layer’s generated Go (internal/wire/rpc/*.pb.go and *.twirp.go) is committed; CI does not regenerate it. Rerun the generator yourself after editing internal/wire/rpc/service.proto:

make proto

Requires protoc, protoc-gen-go, and protoc-gen-twirp on PATH (paths=source_relative keeps the output beside the .proto). Commit the regenerated *.pb.go / *.twirp.go alongside the proto change.

make vendor-rete — admin-UI Rete.js bundle

The committed Rete.js bundle at internal/server/static/vendor/rete/rete.min.js is rebuilt only by:

make vendor-rete

This is the only target that invokes node, and it is a manual, occasional step — a version bump or plugin change. It is deliberately not a dependency of build, test, or CI: the normal build ships the committed blob and never runs node. All npm work happens in a throwaway temp dir, so no node_modules / lockfile lands in the repo. See internal/server/static/vendor/rete/README.md and build/rete/build.sh.

Summary