diff --git a/pkg/inventory/doc.go b/pkg/inventory/doc.go
new file mode 100644
index 0000000..bfc312e
--- /dev/null
+++ b/pkg/inventory/doc.go
@@ -0,0 +1,25 @@
+// Package inventory is the Redis-backed stock + reservation service.
+//
+// Two distinct services coexist in this package and they are NOT
+// redundant; they exist for different callers:
+//
+//   - redis_service.go            — stock levels and basic get/batch/reserve.
+//   - redis_reservation_service.go — cart-shaped reservations (with release
+//                                     + available-quantity semantics, used by
+//                                     go-cart-actor via the adapter).
+//
+// `Level` (level.go) is the canonical shape returned by readers and
+// accepted by writers; it is reused across both services.
+//
+// adapter.go bridges to platform/inventory.ReservationPolicy so other
+// services depend on the platform interface, not on this package.
+//
+// listener.go subscribes to the inventory_changed Redis pub/sub channel
+// and mirrors upstream events into the local cache.
+//
+// TODO: types.go mixes storage types (InventoryItem, InventoryReference)
+// with request types (CartReserveRequest, ReserveRequest). Split into
+// `types/storage.go` and `types/cart.go` so callers can depend on only
+// what they need. Start by moving CartReserveRequest + ReserveRequest to
+// `types/cart.go` and adjusting the imports in cmd/*.
+package inventory