structure

README.md

@@ -1,5 +1,37 @@
 # Commons
 
-## Overview
+**Commons** is the shared type library for Shoal - common types used across all components.
 
-Commons are shared consistent types, optionally with TTP serilization.
+## What it Does
+
+Commons provides consistent, reusable types throughout the Shoal system:
+
+- **Shared data structures** - Types used by Pod, Reef, Reservoir, Dock, Lookout
+- **Optional TTP serialization** - Types can be serialized using TTP (Transport Type Protocol)
+- **Cross-crate consistency** - Ensures all components use the same type definitions
+
+## How to Use
+
+### Dependencies
+
+Add to your `Cargo.toml`:
+```toml
+common = { git = "https://git.methanium.net/shoal/commons.git" }
+```
+
+### Usage
+
+Import common types:
+```rust
+use common::{Task, KrillConfig, ProjectMetadata, ...};
+```
+
+## Purpose
+
+Instead of each component defining its own types, Commons centralizes:
+- Communication message types
+- Task definitions
+- Configuration structures
+- Storage schemas
+
+This ensures type safety and consistency across the entire Shoal ecosystem.