2 files changed, 71 insertions(+), 1 deletions(-)

M README.md
M tarantool-protobuf-scm-1.rockspec

@@ 52,6 52,22 @@ both the binary+JSON and text-format suites passes.
 | Microbenchmark + alloc regression gate (`just bench`) | ✅ |
 | proto2 / editions                | ❌ deferred (separate slice; see [docs/codegen.md](docs/codegen.md)) |
 
+## Install
+
+Until the repository is published on its canonical remote, the
+`source.url` in `tarantool-protobuf-scm-1.rockspec` is aspirational and
+`tt rocks install <url>` will fail. Install from a local checkout
+instead:
+
+```bash
+git clone <this-repo> && cd tarantool-protobuf
+tt rocks make tarantool-protobuf-scm-1.rockspec
+```
+
+That puts the `pb.*` runtime modules under `.rocks/share/tarantool/`.
+The Go plugin still has to be built separately — see "Quick start"
+below.
+
 ## Quick start
 
 ```bash


@@ 64,13 80,30 @@ just test
 
 The plugin emits one `.lua` file per `.proto`. By default the output path
 mirrors the proto package (`package foo.bar; baz.proto` → `foo/bar/baz_pb.lua`),
-required as `foo.bar.baz_pb`. Override the Lua module path with a file option:
+required as `foo.bar.baz_pb`. Two ways to override:
 
 ```proto
+// 1. Per-file, via a proto option:
 import "tarantool/tarantool.proto";
 option (tarantool.lua_package) = "myapp.proto.foo";
 ```
 
+```bash
+# 2. Plugin-wide, via the `prefix=` plugin parameter. Every generated
+#    module is prepended with this namespace and cross-file imports rewrite
+#    to match. Equivalent to applying `option (tarantool.lua_package)` to
+#    every input file, but without touching the .proto.
+protoc --tarantool_out=out \
+       --tarantool_opt=prefix=myapp.proto \
+       file.proto
+# -> out/myapp/proto/<pkg>/<file>_pb.lua, required as
+#    "myapp.proto.<pkg>.<file>_pb"
+```
+
+`prefix=` and `(tarantool.lua_package)` compose: when both are set, the
+prefix is prepended to the option's value. See
+[docs/reference/cli.md](docs/reference/cli.md) for the full mapping.
+
 For a full walk-through that takes a fresh `.proto` to a Tarantool process
 encoding and decoding it, see **[docs/howto/01-first-message.md](docs/howto/01-first-message.md)**.
 


@@ 114,6 147,37 @@ Repeated fields are Lua arrays (1-based, contiguous). 64-bit integers
 `uint64_t` cdata — lossless and the same convention used by Tarantool's
 `net.box`, `msgpack`, and built-in `protobuf` modules.
 
+### Migrating from a Lua proto library that auto-down-casts int64
+
+If you're moving from a library that hands back Lua numbers (silently
+losing precision past 2^53), expect a sweep wherever a cdata value
+crosses into a primitive that doesn't accept it. The four patterns
+that catch out every migrator:
+
+```lua
+local id = msg.user_id  -- cdata: uint64_t
+
+-- 1. log / printf format verbs: %d on cdata raises an error.
+log.info('user %d signed in', tonumber(id))
+
+-- 2. numeric for-loop bounds: `for i = 1, n` requires a Lua number.
+for i = 1, tonumber(msg.row_count) do ... end
+
+-- 3. string.format with %d / %x: same as log.
+local hex = string.format('%016x', tonumber(id))
+
+-- 4. table keys: cdata is hashed by identity, not value, so two
+--    distinct cdata for the same number won't collide. Either convert
+--    to number (if it fits) or use tostring(id) as the key.
+cache[tonumber(id)] = row
+```
+
+`box.tuple` / `net.box` / `msgpack` / Tarantool's `protobuf` all accept
+cdata int64 directly — those paths don't need a `tonumber()`. The
+boundary is *Lua primitives that expect a number*. Past 2^53 (≈ 9e15),
+`tonumber()` silently truncates; if your IDs can be that large, keep
+them as cdata or stringify with `tostring(id):gsub('U?LL$', '')`.
+
 **Three API modes live side-by-side.** Same descriptor, three call shapes —
 the inline (full) generated API is the default, the descriptor-driven runtime
 API is for dynamic schemas, and the lazy API is a zero-copy view for sparse

@@ 1,6 1,12 @@
 package = "tarantool-protobuf"
 version = "scm-1"
 
+-- NOTE: the canonical public remote is not yet published. The URL below
+-- is aspirational (points where the repo will live on sourcecraft.dev).
+-- Until then, install from a local clone:
+--   tt rocks make tarantool-protobuf-scm-1.rockspec
+-- A fresh `tt rocks install` against the URL below will fail with
+-- "no such repository" — see README "Install" section.
 source = {
     url = "git+https://sourcecraft.dev/bigbes/tarantool-protobuf.git",
     branch = "master",