refactor: pre-generate protobuf modules to remove protoc build-time dep

Downstream consumers no longer need protoc installed to compile the
SDK. lib/longbridge/_protos.ex now ships the pre-compiled output of
mix protox.generate (run via the new mix gen_protos alias).

- pre-generate Longbridge.{Control,Quote,Trade}.V1.* into _protos.ex
- drop protos/ from the Hex package files list (not needed by users)
- exclude _protos.ex from mix format and ex_dna (generated code)
- add mix gen_protos alias for regenerating after a .proto change
- remove protoc build-time requirement from README install docs
- document the new workflow in AGENTS.md

Author: gilbertwong96

.ex_dna.exs

@@ -1,7 +1,7 @@
 %{
   min_mass: 55,
   min_occurrences: 2,
-  ignore: ["deps/**", "_build/**", "node_modules/**"],
+  ignore: ["deps/**", "_build/**", "node_modules/**", "lib/longbridge/_protos.ex"],
   excluded_macros: [:schema, :pipe_through, :plug],
   normalize_pipes: true
 }

.formatter.exs

@@ -1,4 +1,7 @@
 # Used by "mix format"
 [
-  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
+  # Pre-generated by `mix protox.generate` from protos/*.proto.
+  # Regenerate with `mix longbridge.gen_protos` (see mix.exs aliases).
+  ignore_files: ["lib/longbridge/_protos.ex"]
 ]

AGENTS.md

@@ -26,7 +26,7 @@ Operating instructions for AI coding agents working on the **longbridge** Elixir
 | `Longbridge.PortfolioContext` | Exchange rates and portfolio P&L analysis. HTTP-only. |
 | `Longbridge.Protocol` | Wire-format constants + `pack/2` / `unpack/1` for whole packets. |
 | `Longbridge.Protocol.Header` | Per-packet header encode/decode (request / response / push layouts). |
-| `Longbridge.Protos` | `use Protox, files: protos/*.proto` — generates `Longbridge.{Control,Quote,Trade}.V1.*` structs. |
+| `Longbridge.Protos` | Pre-generated protobuf modules (`lib/longbridge/_protos.ex`) for `Longbridge.{Control,Quote,Trade}.V1.*` structs. Regenerate with `mix gen_protos` (requires `protoc`, dev-only). |
 | `Longbridge.QuoteContext` | Public API for the quote endpoint — 20+ typed methods. |
 | `Longbridge.SharelistContext` | Community sharelist management. HTTP-only. |
 | `Longbridge.ScreenerContext` | Stock-screener strategies, indicator search, AI recommendations. HTTP-only. Mirrors `ScreenerContext` in `longbridge/openapi-go` and `longbridge/openapi`. |
@@ -61,7 +61,7 @@ mix format              # auto-format
 mix docs                # generate ExDoc HTML
 ```
 
-`protoc` must be on `$PATH` (Elixir `protox` shells out to it). On macOS: `brew install protobuf`.
+`protoc` is **only** required when regenerating protobuf modules (`mix gen_protos`), not for normal `mix compile`/`mix test`. On macOS: `brew install protobuf`. The generated modules ship pre-compiled in `lib/longbridge/_protos.ex`; downstream consumers never need `protoc`.
 
 ## Architecture invariants
 
@@ -83,7 +83,7 @@ mix docs                # generate ExDoc HTML
 - **No `IO.puts` / `IO.inspect` in library code.** Use `Logger` (the connection module already requires it). This includes temporary debugging — use `Logger.debug` and remove before committing.
 - **Specs for public functions.** `@spec` for every public function. Prefer concrete types (`non_neg_integer()`, `:atom | binary()`) over generic ones (`term()`, `any()`).
 - **Match on the struct shape, not just the variable.** When a function expects a `Header.t()`, pattern-match `def f(%Header{} = h, ...)` so Dialyzer can prove the type and you get a clear error if a caller passes the wrong shape.
-- **One `use Protox` only.** The `use Protox, files: [...], paths: [...]` macro call lives **exclusively** in `lib/longbridge/_protos.ex`. The macro generates `Longbridge.{Control,Quote,Trade}.V1.*` modules and the file's name (and `defmodule Longbridge.Protos`) are load-bearing for the generated module names — renaming either one will require updating the `Q.`, `T.`, and `Ctrl.` aliases in `quote_context.ex`, `trade_context.ex`, and `connection.ex`.
+- **Protobuf modules are pre-generated.** `lib/longbridge/_protos.ex` contains the pre-compiled output of `mix protox.generate` (run via the `mix gen_protos` alias). It generates `Longbridge.{Control,Quote,Trade}.V1.*` modules. Do **not** switch back to `use Protox, files: [...]` — that would reintroduce the `protoc` build-time dependency for downstream consumers. The file's name and `defmodule Longbridge.Protos` are load-bearing for the generated module names — renaming either one will require updating the `Q.`, `T.`, and `Ctrl.` aliases in `quote_context.ex`, `trade_context.ex`, and `connection.ex`. To regenerate after a `.proto` change: `mix gen_protos` (requires `protoc`).
 
 ## Tests
 

CHANGELOG.md

@@ -9,12 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Pre-generated protobuf modules** — `lib/longbridge/_protos.ex` now ships
+  the compiled output of `mix protox.generate` instead of using `use Protox,
+  files: [...]`. **Downstream consumers no longer need `protoc` installed** to
+  compile the SDK. `protoc` is only required for maintainers regenerating the
+  modules after a `.proto` change (run `mix gen_protos`). The `protos/` source
+  files are no longer included in the Hex package.
 - **Dropped the `jason` dependency** in favor of the built-in `JSON` module
   (Elixir 1.20+). All encode/decode call sites in `lib/` and `test/` now use
   `JSON.encode!/1` / `JSON.decode/1`. `jason` remains only as a transitive
   dependency of `req` and `ex_doc`.
 - **Removed the redundant License section** from the README; the MIT LICENSE
   file now ships with the package and is linked via the badge.
+- **Removed the `protoc` build-time requirement** from the README installation
+  instructions (no longer needed thanks to pre-generated modules).
 
 ## [0.1.0] — Initial beta release
 

README.md

@@ -24,12 +24,6 @@ def deps do
 end
 ```
 
-`protoc` is a build-time dependency of `protox` (one of the transitive deps). On macOS:
-
-```sh
-brew install protobuf
-```
-
 ## Quick start
 
 ```elixir
@@ -636,7 +630,11 @@ The four `.proto` files under `protos/` are vendored from [`longbridge/openapi-p
 cp deps/openapi_protobuf_specs/control/*.proto protos/
 cp deps/openapi_protobuf_specs/quote/*.proto   protos/
 cp deps/openapi_protobuf_specs/trade/*.proto   protos/
-# 4. mix compile && mix test
+# 4. regenerate the pre-compiled modules (requires protoc)
+mix gen_protos
+# 5. mix compile && mix test
 ```
 
+The protobuf Elixir modules are **pre-generated** into `lib/longbridge/_protos.ex` (via `mix protox.generate`), so downstream consumers do **not** need `protoc` installed. `protoc` is only required for maintainers regenerating the modules after a proto change. Run `mix gen_protos` to regenerate.
+
 Don't hand-edit files under `protos/` — the next sync will clobber your changes.