diff --git a/README.md b/README.md
index 87764f0..8abe1db 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ Orchard is a centralized binary artifact storage system that provides content-ad
   - **Package** - Named collection within a project
   - **Artifact** - Specific content instance identified by SHA256
 - **Tags** - Alias system for referencing artifacts by human-readable names (e.g., `v1.0.0`, `latest`, `stable`)
+- **Package Formats & Platforms** - Packages can be tagged with format (npm, pypi, docker, deb, rpm, etc.) and platform (linux, darwin, windows, etc.)
+- **Rich Package Metadata** - Package listings include aggregated stats (tag count, artifact count, total size, latest tag)
 - **S3-Compatible Backend** - Uses MinIO (or any S3-compatible storage) for artifact storage
 - **PostgreSQL Metadata** - Relational database for metadata, access control, and audit trails
 - **REST API** - Full HTTP API for all operations
@@ -48,7 +50,8 @@ Orchard is a centralized binary artifact storage system that provides content-ad
 | `GET` | `/api/v1/projects` | List all projects |
 | `POST` | `/api/v1/projects` | Create a new project |
 | `GET` | `/api/v1/projects/:project` | Get project details |
-| `GET` | `/api/v1/project/:project/packages` | List packages in a project |
+| `GET` | `/api/v1/project/:project/packages` | List packages (with pagination, search, filtering) |
+| `GET` | `/api/v1/project/:project/packages/:package` | Get single package with metadata |
 | `POST` | `/api/v1/project/:project/packages` | Create a new package |
 | `POST` | `/api/v1/project/:project/:package/upload` | Upload an artifact |
 | `GET` | `/api/v1/project/:project/:package/+/:ref` | Download an artifact (supports Range header) |
@@ -151,7 +154,61 @@ curl -X POST http://localhost:8080/api/v1/projects \
 ```bash
 curl -X POST http://localhost:8080/api/v1/project/my-project/packages \
   -H "Content-Type: application/json" \
-  -d '{"name": "releases", "description": "Release builds"}'
+  -d '{"name": "releases", "description": "Release builds", "format": "generic", "platform": "any"}'
+```
+
+Supported formats: `generic`, `npm`, `pypi`, `docker`, `deb`, `rpm`, `maven`, `nuget`, `helm`
+
+Supported platforms: `any`, `linux`, `darwin`, `windows`, `linux-amd64`, `linux-arm64`, `darwin-amd64`, `darwin-arm64`, `windows-amd64`
+
+### List Packages
+
+```bash
+# Basic listing
+curl http://localhost:8080/api/v1/project/my-project/packages
+
+# With pagination
+curl "http://localhost:8080/api/v1/project/my-project/packages?page=1&limit=10"
+
+# With search
+curl "http://localhost:8080/api/v1/project/my-project/packages?search=release"
+
+# With sorting
+curl "http://localhost:8080/api/v1/project/my-project/packages?sort=created_at&order=desc"
+
+# Filter by format/platform
+curl "http://localhost:8080/api/v1/project/my-project/packages?format=npm&platform=linux"
+```
+
+Response includes aggregated metadata:
+```json
+{
+  "items": [
+    {
+      "id": "uuid",
+      "name": "releases",
+      "description": "Release builds",
+      "format": "generic",
+      "platform": "any",
+      "tag_count": 5,
+      "artifact_count": 3,
+      "total_size": 1048576,
+      "latest_tag": "v1.0.0",
+      "latest_upload_at": "2025-01-01T00:00:00Z",
+      "recent_tags": [...]
+    }
+  ],
+  "pagination": {"page": 1, "limit": 20, "total": 1, "total_pages": 1}
+}
+```
+
+### Get Single Package
+
+```bash
+curl http://localhost:8080/api/v1/project/my-project/packages/releases
+
+# Include all tags (not just recent 5)
+curl "http://localhost:8080/api/v1/project/my-project/packages/releases?include_tags=true"
 ```
 
 ### Upload an Artifact