Preserve Gotlin semantics across packages

README.md

@@ -12,6 +12,10 @@ The compiler keeps source spelling in its syntax AST, then builds lexical
 symbols, structural semantic types, resolved expression meanings, and typed
 HIR before Go emission. Class reference semantics live in `ClassType`; only
 the semantic Type-to-Go mapping turns a class such as `User` into `*User`.
+Separately compiled Gotlin packages publish a versioned `.gti.json` interface;
+imports load that interface before falling back to `go/types`, preserving class
+reference semantics, generics, enums, function signatures, and inferred effects
+across package boundaries.
 
 ## Supported language slice
 
@@ -268,6 +272,14 @@ go run ./cmd/gotlinc build -src ./examples/hello.gt -o /tmp/hello.go
 go run /tmp/hello.go
 ```
 
+Emit or consume package interfaces with repeatable metadata flags:
+
+```bash
+gotlinc build -src -metadata-output platform.gti.json \
+  -metadata-package example/platform platform.gt -o platform.go
+gotlinc build -src -metadata platform.gti.json service.gt -o service.go
+```
+
 Run directly:
 
 ```bash