diff --git a/pageserver/client_grpc/src/lib.rs b/pageserver/client_grpc/src/lib.rs
index aeba354bc8..384994ba38 100644
--- a/pageserver/client_grpc/src/lib.rs
+++ b/pageserver/client_grpc/src/lib.rs
@@ -17,9 +17,9 @@ use pageserver_page_api::proto;
 
 type Shardno = u16;
 
-use pageserver_page_api::client::PageServiceClient;
+use pageserver_page_api::proto::PageServiceClient;
 
-type MyPageServiceClient = pageserver_page_api::client::PageServiceClient<
+type MyPageServiceClient = pageserver_page_api::proto::PageServiceClient<
     tonic::service::interceptor::InterceptedService<tonic::transport::Channel, AuthInterceptor>,
 >;
 
diff --git a/pageserver/page_api/build.rs b/pageserver/page_api/build.rs
index 4af621df1c..6739222ed0 100644
--- a/pageserver/page_api/build.rs
+++ b/pageserver/page_api/build.rs
@@ -3,6 +3,5 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     tonic_build::configure()
         .bytes(["."])
         .compile_protos(&["proto/page_service.proto"], &["proto"])
-        .unwrap_or_else(|e| panic!("failed to compile protos {:?}", e));
-    Ok(())
+        .map_err(|err| err.into())
 }
diff --git a/pageserver/page_api/src/lib.rs b/pageserver/page_api/src/lib.rs
index 3c0963ae1c..b87db7eaa2 100644
--- a/pageserver/page_api/src/lib.rs
+++ b/pageserver/page_api/src/lib.rs
@@ -1,17 +1,19 @@
-//! This crate has two modules related to the Pageserver Data API:
+//! This crate provides the Pageserver's page API. It contains:
 //!
-//! proto: code auto-generated from the protobuf definition
-//! model: slightly more ergonomic structs representing the same API
+//! * proto: auto-generated Protobuf types for gRPC.
+//! * model: canonical domain types. Protobuf types are converted into these.
 //!
-//! See protobuf spec under the protos/ subdirectory.
+//! See `proto/page_service.proto` for the protocol spec.
 //!
 //! This crate is used by both the client and the server. Try to keep it slim.
 //!
+
 pub mod model;
 
 // Code generated by protobuf.
 pub mod proto {
     tonic::include_proto!("page_service");
-}
 
-pub use proto::page_service_client as client;
+    pub use page_service_client::PageServiceClient;
+    pub use page_service_server::PageServiceServer;
+}
diff --git a/pageserver/page_api/src/model.rs b/pageserver/page_api/src/model.rs
index 85faa131e2..30b5f0be52 100644
--- a/pageserver/page_api/src/model.rs
+++ b/pageserver/page_api/src/model.rs
@@ -1,4 +1,4 @@
-//! Structs representing the API
+//! Structs representing the canonical page service API.
 //!
 //! These mirror the pageserver APIs and the structs automatically generated
 //! from the protobuf specification. The differences are:
@@ -8,6 +8,9 @@
 //!   (See https://github.com/tokio-rs/prost/issues/800 for a gripe on this)
 //!
 //! - Use more precise datatypes, e.g. Lsn and uints shorter than 32 bits.
+//!
+//! TODO: these types should be used in the Pageserver for actual processing,
+//! instead of being cast into internal mirror types.
 
 use utils::lsn::Lsn;