The Quiet Documentation Fix: Adding protobuf-compiler to Installation Guides

"In install documentation/ add (apt) protobuf-compiler to list of deps (also to other distros mentioned there), since this is now required by cuzk"

This brief user request, appearing at <msg id=208>, set in motion a chain of edits that would span two languages, six Linux distributions, and a dozen distinct locations across the Curio project's installation documentation. The subject message — <msg id=221> — is deceptively simple: a single line confirming that an edit to /tmp/czk/documentation/en/installation.md was applied successfully. But this message is not an island. It is the second of six sequential edits to the English installation file, part of a larger, methodical documentation update that the assistant executed after resolving a deep and subtle bug in the CuZK proving engine's Pre-Compiled Constraint Evaluator (PCE) pipeline.

To understand why this documentation update mattered, one must first understand the context in which it arose.

The Context: A New Dependency Emerges from a Bug Hunt

The assistant had just spent several rounds debugging a crash that occurred when PCE extraction was enabled for WindowPoSt proofs. The root cause was a mismatch in the is_extensible() flag between RecordingCS (used during PCE extraction) and WitnessCS (used during witness generation). The fix required harmonizing the initialization behavior of three distinct constraint system types — WitnessCS, RecordingCS, and ProvingAssignment — so that all three started with zero inputs, with the mandatory "ONE" input explicitly allocated by the caller before synthesis began (see <msg id=205> for the full summary).

This fix was subtle and deep. It touched the vendored bellperson crate, the cuzk-core pipeline module, and the cuzk-pce recording module. It required understanding how synthesize_extendable creates child constraint systems, how extend() skips the first input, and how a single pre-allocated ONE in WitnessCS::new() could cascade into 196 extra inputs across parallel partitions. The assistant traced this through multiple files, ran cargo check to verify compilation, and reasoned carefully about whether the change would affect other paths like generate_witness_into_cs or the existing PoRep PCE on disk.

After this intense debugging session, the user issued a request that seems mundane by comparison: update the installation documentation to list protobuf-compiler as a dependency. But this request was not arbitrary. The CuZK proving engine, which the assistant had been actively developing and debugging, had acquired a new build dependency. The protobuf-compiler package provides the protoc binary, which is needed to compile .proto files used in the CuZK daemon's gRPC interface or similar serialization layers. Without this dependency listed in the installation guides, users building from source on a fresh system would encounter cryptic build failures — missing protoc errors that would derail the setup experience.

The Assistant's Systematic Approach

The assistant's response to the user's request demonstrates a methodical, thorough approach to documentation maintenance. Rather than making a single edit and moving on, the assistant first surveyed the entire documentation tree to understand the full scope of the change.

The assistant began by searching for installation documentation files using glob and grep commands (<msg id=209> through <msg id=218>). It found two versions of the installation guide — English and Chinese — and also checked the supraseal.md file for any dependency lists that might need updating. This cross-referencing step was crucial: the assistant needed to ensure that protobuf-compiler was added not just to the Debian/Ubuntu apt commands (as the user specifically mentioned), but to every distribution's package manager command listed in the documentation.

In <msg id=219>, the assistant laid out a complete inventory of all locations requiring edits:

The Edit Sequence: Message 221 in Context

Message <msg id=221> is the second edit in a sequence of six edits to the English installation file, followed by six edits to the Chinese installation file. The sequence runs from <msg id=220> through <msg id=226>. Each edit applies a targeted change to a specific line or block in the markdown file.

The first edit (<msg id=220>) likely added protobuf-compiler to the Debian package prerequisites line. Message <msg id=221> — the subject of this article — applied the second edit, probably adding the package to the Arch Linux pacman command or another distribution's section. The assistant then continued with <msg id=222>, <msg id=223>, and <msg id=224> for the remaining English locations, before moving on to the Chinese documentation in <msg id=225> and <msg id=226>.

The fact that the assistant chose to make six separate edits rather than one large edit is interesting. It suggests a deliberate strategy of applying changes incrementally, perhaps to keep each edit focused and auditable. In a collaborative development environment, granular edits make it easier to review changes, revert specific modifications, and understand what was changed where. This approach also reduces the risk of a single large edit accidentally corrupting the file.

Input Knowledge Required

To understand this message and the documentation update it represents, several pieces of knowledge are necessary:

  1. The CuZK project structure: The reader must know that cuzk is a proving engine for Filecoin proofs, that it lives under extern/cuzk/ in the Curio repository, and that it has recently introduced a dependency on protobuf-compiler for compiling protocol buffer definitions.
  2. The PCE extraction work: The documentation update follows directly from the assistant's work implementing PCE extraction for all proof types. The protobuf-compiler dependency likely arose from the gRPC or serialization infrastructure needed by the CuZK daemon, which performs background PCE extraction and GPU proving.
  3. Linux package management conventions: The assistant's edit correctly accounts for the fact that different distributions use different package names for protobuf tools. On Debian-based systems, the package is protobuf-compiler; on Arch, it's simply protobuf; on OpenSUSE, it's protobuf-devel. Understanding these naming conventions is essential for writing accurate cross-distribution documentation.
  4. The documentation structure: The Curio project maintains installation guides in both English (documentation/en/installation.md) and Chinese (documentation/zh/installation.md), each covering the same set of distributions. The assistant needed to locate and update both files.

Output Knowledge Created

This message, as part of the documentation update, creates several forms of knowledge:

  1. Actionable installation instructions: Users building Curio from source now have accurate, complete dependency lists that include protobuf-compiler. This prevents build failures caused by missing protoc.
  2. Cross-distribution coverage: The update covers six Linux distributions across two languages, ensuring that users on any supported platform can find the correct package name and installation command.
  3. A record of the dependency change: The documentation update serves as a historical record that protobuf-compiler became a required dependency at this point in the project's development, coinciding with the PCE extraction work.
  4. Confidence in the build process: By keeping the documentation in sync with the actual build requirements, the update reduces friction for new contributors and users who might otherwise waste time debugging missing dependencies.

Assumptions and Potential Mistakes

The assistant made several assumptions during this documentation update:

  1. That protobuf-compiler is the correct package name for all listed distributions. While this is true for Debian, Ubuntu, Fedora, and Amazon Linux, the assistant correctly identified that Arch uses protobuf and OpenSUSE uses protobuf-devel. This assumption was validated by the assistant's research into distro-specific naming.
  2. That the Chinese documentation should receive the same updates as the English version. This is a reasonable assumption for a project that maintains bilingual documentation, but it does assume that the Chinese translation is kept in sync with the English original. If the Chinese version had diverged, blindly applying the same edits could have introduced inconsistencies.
  3. That no other files need updating. The assistant checked supraseal.md for dependency lists and found none that needed modification. However, there could be other documentation files (e.g., Dockerfiles, CI configuration, or developer setup guides) that also reference dependencies. The assistant's search was thorough but not exhaustive.
  4. That the user's request implies updating all distributions, not just apt. The user said "add (apt) protobuf-compiler to list of deps (also to other distros mentioned there)." The assistant interpreted "also to other distros" as an instruction to update every distribution's package list, which was the correct and thorough interpretation.

The Broader Significance

While a documentation update might seem trivial compared to the deep constraint-system debugging that preceded it, this message represents an essential part of the software development lifecycle. The assistant had just introduced changes to the CuZK proving engine that added a new build dependency. Without updating the installation documentation, those changes would have created a gap between what the code requires and what users know they need to install.

In open-source projects, documentation is the bridge between developers and users. A missing dependency in the installation guide can waste hours of a user's time, generate support requests, and create a negative first impression. By systematically updating both language versions and all six distribution sections, the assistant ensured that this bridge remained intact.

The message <msg id=221> — "Edit applied successfully" — is the sound of one small piece of that bridge being laid. It is unremarkable on its own, but it is part of a larger pattern of thoroughness and attention to detail that characterizes the assistant's work throughout this session. The same assistant that traced a 196-input mismatch through three constraint system implementations also took the time to ensure that users on Arch Linux would know to run pacman -S protobuf before building Curio. That consistency — treating documentation with the same rigor as code — is what makes the difference between a project that works and a project that works for its users.