diff --git a/README.md b/README.md
index 6b8923a..6a2843d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,26 @@
 # canvas-openapi
 
-Auto-generated OpenAPI specification for Canvas LMS
\ No newline at end of file
+Auto-generated OpenAPI 3.0.3 specification for the [Canvas LMS](https://github.com/instructure/canvas-lms) REST API.
+
+## Overview
+
+This spec was generated from a local Canvas LMS instance built from source, covering **1005 paths** across all Canvas REST API endpoints. It provides a machine-readable description of the full Canvas API surface.
+
+## Authentication
+
+The spec includes a **Bearer Token** authentication scheme. Generate a token in Canvas under Account > Settings > Approved Integrations, then pass it as:
+
+```
+Authorization: Bearer <your_token>
+```
+
+## Usage
+
+- **Swagger UI** -- Load the spec file to browse and test endpoints interactively
+- **Postman** -- Import the spec to generate a complete Canvas API collection
+- **Code generation** -- Use [openapi-generator](https://openapi-generator.tech/) or similar tools to generate client libraries in any language
+
+```bash
+# Example: generate a Python client
+openapi-generator-cli generate -i openapi.json -g python -o ./canvas-client
+```