diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..7a8e924
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,22 @@
+name: Validate OpenAPI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Validate OpenAPI spec
+        run: npx --yes @redocly/cli lint openapi.yaml
+
diff --git a/README.md b/README.md
index d93f9e8..7350551 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,35 @@
 # Supermodel OpenAPI Specification
-Read more: [https://docs.supermodeltools.com](https://docs.supermodeltools.com)
+
+[![npm](https://img.shields.io/npm/v/@supermodeltools/openapi-spec)](https://www.npmjs.com/package/@supermodeltools/openapi-spec)
+[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0-green)](https://spec.openapis.org/oas/v3.0.0)
+
+OpenAPI 3.0 specification for the [Supermodel API](https://docs.supermodeltools.com) - code graphing and static analysis.
+
+## Install
+
+```bash
+npm install @supermodeltools/openapi-spec
+```
+
+The spec is available at `node_modules/@supermodeltools/openapi-spec/openapi.yaml`.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/graphs/dependency` | File-level dependency graph |
+| POST | `/v1/graphs/call` | Function-level call graph |
+| POST | `/v1/graphs/domain` | Domain model classification |
+| POST | `/v1/graphs/parse` | AST parse tree relationships |
+| POST | `/v1/graphs/supermodel` | Full Supermodel IR bundle |
+
+All endpoints accept a zipped repository snapshot and return graph data as JSON.
+
+## Authentication
+
+Requests require an API key via `X-Api-Key` header.
+
+## Links
+
+- [API Documentation](https://docs.supermodeltools.com)
+- [API Terms of Service](https://supermodeltools.com/legal/api-terms)
diff --git a/package.json b/package.json
index f3c6abd..7f252f9 100644
--- a/package.json
+++ b/package.json
@@ -10,6 +10,20 @@
     "type": "git",
     "url": "git+https://github.com/supermodeltools/openapi-spec.git"
   },
+  "homepage": "https://docs.supermodeltools.com",
+  "bugs": {
+    "url": "https://github.com/supermodeltools/openapi-spec/issues"
+  },
+  "keywords": [
+    "openapi",
+    "api",
+    "code-graph",
+    "dependency-graph",
+    "call-graph",
+    "static-analysis",
+    "code-analysis",
+    "supermodel"
+  ],
   "author": "Supermodel <abe@supermodel.software>",
   "license": "UNLICENSED"
 }