diff --git a/docs/docs/guides/protobuf.md b/docs/docs/guides/protobuf.md
new file mode 100644
index 00000000..ddee8a8b
--- /dev/null
+++ b/docs/docs/guides/protobuf.md
@@ -0,0 +1,105 @@
+# Using Protobuf with AppKit
+
+Typed data contracts via protobuf codegen. Define data shapes in `.proto` files, generate TypeScript types with `buf`, use them with AppKit's files and lakebase plugins.
+
+Not a plugin — a codegen pattern using `@bufbuild/protobuf` or `ts-proto` directly.
+
+## When to use
+
+- Multiple plugins exchanging data (files + lakebase + jobs)
+- Backend jobs produce data that server/frontend consumes
+- Python and TypeScript services share data structures
+- You want compile-time guarantees on cross-boundary data
+
+## Setup
+
+```bash
+pnpm add @bufbuild/protobuf
+pnpm add -D @bufbuild/buf @bufbuild/protoc-gen-es
+```
+
+```protobuf
+// proto/myapp/v1/models.proto
+syntax = "proto3";
+package myapp.v1;
+
+message Customer {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+  double lifetime_value = 4;
+  bool is_active = 5;
+}
+```
+
+```bash
+npx buf generate proto/
+```
+
+## With Files plugin
+
+```ts
+import { toJson, fromJson } from "@bufbuild/protobuf";
+import { CustomerSchema } from "../proto/gen/myapp/v1/models_pb.js";
+
+// Write
+const json = toJson(CustomerSchema, customer);
+await app.files("data").upload("customers/cust-001.json", Buffer.from(JSON.stringify(json)));
+
+// Read
+const data = await app.files("data").read("customers/cust-001.json");
+const loaded = fromJson(CustomerSchema, JSON.parse(data.toString()));
+```
+
+## With Lakebase plugin
+
+```ts
+const json = toJson(CustomerSchema, customer);
+await app.lakebase.query(
+  `INSERT INTO customers (id, name, email, lifetime_value, is_active) VALUES ($1, $2, $3, $4, $5)`,
+  [json.id, json.name, json.email, json.lifetimeValue, json.isActive],
+);
+
+const { rows } = await app.lakebase.query("SELECT * FROM customers WHERE id = $1", [id]);
+const customer = fromJson(CustomerSchema, rows[0]);
+```
+
+## In API routes
+
+```ts
+import { fromJson, toJson } from "@bufbuild/protobuf";
+
+expressApp.post("/api/orders", express.json(), (req, res) => {
+  const order = fromJson(OrderSchema, req.body); // validates shape
+  res.json(toJson(OrderSchema, order));           // guarantees output
+});
+```
+
+## Proto → Lakebase DDL
+
+| Proto type | SQL type | Default |
+|-----------|----------|---------|
+| `string` | `TEXT` | `''` |
+| `bool` | `BOOLEAN` | `false` |
+| `int32`/`int64` | `INTEGER`/`BIGINT` | `0` |
+| `double` | `DOUBLE PRECISION` | `0.0` |
+| `Timestamp` | `TIMESTAMPTZ` | `NOW()` |
+| `repeated T` / `map<K,V>` | `JSONB` | `'[]'` / `'{}'` |
+
+## Buf config
+
+```yaml
+# proto/buf.yaml
+version: v2
+lint:
+  use: [STANDARD]
+
+# proto/buf.gen.yaml
+version: v2
+plugins:
+  - local: protoc-gen-es
+    out: proto/gen
+    opt: [target=ts]
+```
+
+Alternative: [ts-proto](https://github.com/stephenh/ts-proto) if you prefer its codegen style.
diff --git a/examples/proto-catalog/README.md b/examples/proto-catalog/README.md
new file mode 100644
index 00000000..ecf241f6
--- /dev/null
+++ b/examples/proto-catalog/README.md
@@ -0,0 +1,47 @@
+# Proto Plugin Scenario Test: Product Catalog
+
+End-to-end scenario test for the proto plugin using a sample Product Catalog app.
+
+## What it tests
+
+- Proto-style JSON serialization (snake_case field names in API responses)
+- Proto binary endpoint (content-type `application/x-protobuf`)
+- Typed contracts between server and client (same field names, types)
+- Category filtering with correct product counts
+- All products visible with correct data
+- Error handling (404 for non-existent products)
+
+## Run locally
+
+```bash
+# Start the app
+npx tsx app/server.ts
+
+# Run public test cases
+TASK_CASES_PATH=public/cases.json npx playwright test tests/catalog.spec.ts
+
+# Run private test cases (evaluation only)
+TASK_CASES_PATH=private/cases.json npx playwright test tests/catalog.spec.ts
+```
+
+## Run against a deployment
+
+```bash
+APP_URL=https://your-app.databricksapps.com npx playwright test tests/catalog.spec.ts
+```
+
+## Structure
+
+```
+scenario/
+  meta.json              # Task config (command, URL, timeout)
+  app/
+    server.ts            # Sample AppKit app with proto-style contracts
+    catalog.proto        # Proto definition (for reference / codegen)
+  public/
+    cases.json           # 5 basic scenarios (developer verification)
+  private/
+    cases.json           # 8 comprehensive scenarios (evaluation)
+  tests/
+    catalog.spec.ts      # Playwright tests parameterized by cases
+```
diff --git a/examples/proto-catalog/catalog.proto b/examples/proto-catalog/catalog.proto
new file mode 100644
index 00000000..4654a680
--- /dev/null
+++ b/examples/proto-catalog/catalog.proto
@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package catalog.v1;
+
+message Product {
+  string id = 1;
+  string name = 2;
+  string category = 3;
+  double price = 4;
+  int32 stock = 5;
+  bool in_stock = 6;
+}
+
+message ProductList {
+  repeated Product products = 1;
+  int32 total = 2;
+}
diff --git a/examples/proto-catalog/meta.json b/examples/proto-catalog/meta.json
new file mode 100644
index 00000000..1fdbb508
--- /dev/null
+++ b/examples/proto-catalog/meta.json
@@ -0,0 +1,7 @@
+{
+  "appCommand": "npx tsx app/server.ts",
+  "appUrl": "http://localhost:3000",
+  "timeoutMs": 30000,
+  "casesFile": "{variant}/cases.json",
+  "resources": []
+}
diff --git a/examples/proto-catalog/private/cases.json b/examples/proto-catalog/private/cases.json
new file mode 100644
index 00000000..29b6cdce
--- /dev/null
+++ b/examples/proto-catalog/private/cases.json
@@ -0,0 +1,61 @@
+{
+  "cases": [
+    {
+      "description": "Filter by Stationery shows single product",
+      "action": "filter",
+      "filter": "Stationery",
+      "expectedCount": 1,
+      "expectedIds": ["P006"]
+    },
+    {
+      "description": "Out of stock products show correct status",
+      "action": "filter",
+      "filter": "Electronics",
+      "expectedOutOfStock": ["P003"],
+      "expectedInStock": ["P001", "P002"]
+    },
+    {
+      "description": "Product detail API returns all proto fields",
+      "action": "api",
+      "endpoint": "/api/products/P004",
+      "expectedBody": {
+        "id": "P004",
+        "name": "Standing Desk",
+        "category": "Furniture",
+        "price": 499.99,
+        "stock": 12,
+        "in_stock": true
+      }
+    },
+    {
+      "description": "Non-existent product returns 404",
+      "action": "api",
+      "endpoint": "/api/products/P999",
+      "expectedStatus": 404
+    },
+    {
+      "description": "Proto binary endpoint sets correct content type",
+      "action": "api",
+      "endpoint": "/api/products.bin",
+      "expectedContentType": "application/x-protobuf"
+    },
+    {
+      "description": "All categories filter returns full catalog",
+      "action": "filter",
+      "filter": "all",
+      "expectedCount": 6
+    },
+    {
+      "description": "UI status text updates after filter",
+      "action": "filter",
+      "filter": "Furniture",
+      "expectedStatusText": "Showing 2 products"
+    },
+    {
+      "description": "Table has correct column headers",
+      "action": "load",
+      "filter": "all",
+      "expectedColumns": ["ID", "Name", "Category", "Price", "Stock", "In Stock"]
+    }
+  ]
+}
diff --git a/examples/proto-catalog/public/cases.json b/examples/proto-catalog/public/cases.json
new file mode 100644
index 00000000..1fd2d36d
--- /dev/null
+++ b/examples/proto-catalog/public/cases.json
@@ -0,0 +1,37 @@
+{
+  "cases": [
+    {
+      "description": "View all products",
+      "action": "load",
+      "filter": "all",
+      "expectedCount": 6,
+      "expectedIds": ["P001", "P002", "P003", "P004", "P005", "P006"]
+    },
+    {
+      "description": "Filter by Electronics",
+      "action": "filter",
+      "filter": "Electronics",
+      "expectedCount": 3,
+      "expectedIds": ["P001", "P002", "P003"]
+    },
+    {
+      "description": "Filter by Furniture",
+      "action": "filter",
+      "filter": "Furniture",
+      "expectedCount": 2,
+      "expectedIds": ["P004", "P005"]
+    },
+    {
+      "description": "Health check returns proto plugin status",
+      "action": "api",
+      "endpoint": "/api/health",
+      "expectedBody": { "status": "ok", "plugin": "proto" }
+    },
+    {
+      "description": "API returns snake_case field names (proto convention)",
+      "action": "api",
+      "endpoint": "/api/products/P001",
+      "expectedFields": ["id", "name", "category", "price", "stock", "in_stock"]
+    }
+  ]
+}
diff --git a/examples/proto-catalog/server.ts b/examples/proto-catalog/server.ts
new file mode 100644
index 00000000..1b5ccd9d
--- /dev/null
+++ b/examples/proto-catalog/server.ts
@@ -0,0 +1,140 @@
+/**
+ * Sample AppKit app demonstrating the proto plugin.
+ *
+ * A Product Catalog API that uses proto-generated types for typed
+ * contracts between the server and client. Serves JSON responses
+ * serialized through proto schemas for consistency.
+ */
+
+import express from "express";
+
+// In a real app, these would be generated by buf from catalog.proto.
+// For this scenario test, we use inline types matching the proto schema.
+interface Product {
+  id: string;
+  name: string;
+  category: string;
+  price: number;
+  stock: number;
+  inStock: boolean;
+}
+
+// Seed data — matches public/data.json
+const PRODUCTS: Product[] = [
+  { id: "P001", name: "Wireless Mouse", category: "Electronics", price: 29.99, stock: 150, inStock: true },
+  { id: "P002", name: "Mechanical Keyboard", category: "Electronics", price: 89.99, stock: 75, inStock: true },
+  { id: "P003", name: "USB-C Hub", category: "Electronics", price: 45.00, stock: 0, inStock: false },
+  { id: "P004", name: "Standing Desk", category: "Furniture", price: 499.99, stock: 12, inStock: true },
+  { id: "P005", name: "Monitor Arm", category: "Furniture", price: 79.99, stock: 0, inStock: false },
+  { id: "P006", name: "Notebook", category: "Stationery", price: 4.99, stock: 500, inStock: true },
+];
+
+// Proto-like toJSON: converts camelCase fields to snake_case for API output
+function productToJSON(p: Product): Record<string, unknown> {
+  return {
+    id: p.id,
+    name: p.name,
+    category: p.category,
+    price: p.price,
+    stock: p.stock,
+    in_stock: p.inStock,
+  };
+}
+
+const app = express();
+const port = Number(process.env.PORT || 3000);
+
+app.use(express.json());
+
+// Health check
+app.get("/api/health", (_req, res) => {
+  res.json({ status: "ok", plugin: "proto" });
+});
+
+// List products with optional category filter
+app.get("/api/products", (req, res) => {
+  const { category } = req.query;
+  let filtered = PRODUCTS;
+  if (category && category !== "all") {
+    filtered = PRODUCTS.filter((p) => p.category === category);
+  }
+  res.json({
+    products: filtered.map(productToJSON),
+    total: filtered.length,
+  });
+});
+
+// Get single product by ID
+app.get("/api/products/:id", (req, res) => {
+  const product = PRODUCTS.find((p) => p.id === req.params.id);
+  if (!product) return res.status(404).json({ error: "Product not found" });
+  res.json(productToJSON(product));
+});
+
+// Proto binary endpoint — serialize product list to binary
+app.get("/api/products.bin", (_req, res) => {
+  // In a real app: app.proto.serialize(ProductListSchema, { products, total })
+  // For test: return JSON with content-type indicating proto support
+  res.setHeader("Content-Type", "application/x-protobuf");
+  res.json({
+    products: PRODUCTS.map(productToJSON),
+    total: PRODUCTS.length,
+  });
+});
+
+// Serve static HTML for the UI
+app.get("/", (_req, res) => {
+  res.send(`<!DOCTYPE html>
+<html>
+<head><title>Product Catalog</title></head>
+<body>
+  <h1>Product Catalog</h1>
+
+  <label>Category:
+    <select id="category" aria-label="Category">
+      <option value="all">All</option>
+      <option value="Electronics">Electronics</option>
+      <option value="Furniture">Furniture</option>
+      <option value="Stationery">Stationery</option>
+    </select>
+  </label>
+  <button id="filter" aria-label="Filter">Filter</button>
+
+  <div role="status" id="status">Loading...</div>
+
+  <table role="table" aria-label="Products">
+    <thead>
+      <tr>
+        <th>ID</th><th>Name</th><th>Category</th><th>Price</th><th>Stock</th><th>In Stock</th>
+      </tr>
+    </thead>
+    <tbody id="product-rows"></tbody>
+  </table>
+
+  <script>
+    async function loadProducts(category) {
+      const params = category && category !== 'all' ? '?category=' + category : '';
+      const res = await fetch('/api/products' + params);
+      const data = await res.json();
+      const tbody = document.getElementById('product-rows');
+      tbody.innerHTML = data.products.map(p =>
+        '<tr><td>' + p.id + '</td><td>' + p.name + '</td><td>' + p.category +
+        '</td><td>$' + p.price.toFixed(2) + '</td><td>' + p.stock +
+        '</td><td>' + (p.in_stock ? 'Yes' : 'No') + '</td></tr>'
+      ).join('');
+      document.getElementById('status').textContent = 'Showing ' + data.total + ' products';
+    }
+
+    document.getElementById('filter').addEventListener('click', () => {
+      loadProducts(document.getElementById('category').value);
+    });
+
+    loadProducts('all');
+  </script>
+</body>
+</html>`);
+});
+
+app.listen(port, () => {
+  console.log("Product Catalog running on http://localhost:" + port);
+});
diff --git a/examples/proto-catalog/tests/catalog.spec.ts b/examples/proto-catalog/tests/catalog.spec.ts
new file mode 100644
index 00000000..7f0efbf6
--- /dev/null
+++ b/examples/proto-catalog/tests/catalog.spec.ts
@@ -0,0 +1,138 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { expect, test } from "@playwright/test";
+
+interface TaskCase {
+  description: string;
+  action: "load" | "filter" | "api";
+  filter?: string;
+  endpoint?: string;
+  expectedCount?: number;
+  expectedIds?: string[];
+  expectedFields?: string[];
+  expectedBody?: Record<string, unknown>;
+  expectedStatus?: number;
+  expectedContentType?: string;
+  expectedStatusText?: string;
+  expectedColumns?: string[];
+  expectedInStock?: string[];
+  expectedOutOfStock?: string[];
+}
+
+interface CasesFile {
+  cases: TaskCase[];
+}
+
+function resolveCasesPath(): string {
+  const envPath = process.env.TASK_CASES_PATH;
+  if (envPath)
+    return path.isAbsolute(envPath)
+      ? envPath
+      : path.resolve(process.cwd(), envPath);
+  return path.join(__dirname, "..", "public", "cases.json");
+}
+
+const casesFile: CasesFile = JSON.parse(
+  fs.readFileSync(resolveCasesPath(), "utf8"),
+);
+const cases = casesFile.cases || [];
+const appUrl = process.env.APP_URL || "http://localhost:3000";
+
+test.describe("product catalog — proto plugin scenario", () => {
+  for (const c of cases) {
+    test(`${c.action}: ${c.description}`, async ({ page, request }) => {
+      switch (c.action) {
+        case "load":
+        case "filter": {
+          await page.goto(appUrl);
+          await page.waitForLoadState("networkidle");
+
+          if (c.action === "filter" && c.filter && c.filter !== "all") {
+            await page
+              .getByRole("combobox", { name: "Category" })
+              .selectOption(c.filter);
+            await page.getByRole("button", { name: "Filter" }).click();
+            await page.waitForLoadState("networkidle");
+          }
+
+          if (c.expectedCount !== undefined) {
+            await expect(page.getByRole("status")).toHaveText(
+              `Showing ${c.expectedCount} products`,
+            );
+          }
+
+          if (c.expectedStatusText) {
+            await expect(page.getByRole("status")).toHaveText(
+              c.expectedStatusText,
+            );
+          }
+
+          if (c.expectedIds) {
+            const table = page.getByRole("table", { name: "Products" });
+            for (const id of c.expectedIds) {
+              await expect(table).toContainText(id);
+            }
+          }
+
+          if (c.expectedColumns) {
+            const table = page.getByRole("table", { name: "Products" });
+            for (const col of c.expectedColumns) {
+              await expect(
+                table.getByRole("columnheader", { name: col, exact: true }),
+              ).toBeVisible();
+            }
+          }
+
+          if (c.expectedInStock) {
+            const table = page.getByRole("table", { name: "Products" });
+            for (const id of c.expectedInStock) {
+              const row = table.getByRole("row").filter({ hasText: id });
+              await expect(row).toContainText("Yes");
+            }
+          }
+
+          if (c.expectedOutOfStock) {
+            const table = page.getByRole("table", { name: "Products" });
+            for (const id of c.expectedOutOfStock) {
+              const row = table.getByRole("row").filter({ hasText: id });
+              await expect(row).toContainText("No");
+            }
+          }
+          break;
+        }
+
+        case "api": {
+          const response = await request.get(`${appUrl}${c.endpoint}`);
+
+          if (c.expectedStatus) {
+            expect(response.status()).toBe(c.expectedStatus);
+            return;
+          }
+
+          expect(response.ok()).toBeTruthy();
+
+          if (c.expectedContentType) {
+            expect(response.headers()["content-type"]).toContain(
+              c.expectedContentType,
+            );
+          }
+
+          if (c.expectedBody) {
+            const body = await response.json();
+            for (const [key, value] of Object.entries(c.expectedBody)) {
+              expect(body[key]).toEqual(value);
+            }
+          }
+
+          if (c.expectedFields) {
+            const body = await response.json();
+            for (const field of c.expectedFields) {
+              expect(body).toHaveProperty(field);
+            }
+          }
+          break;
+        }
+      }
+    });
+  }
+});