diff --git a/spec/README.md b/spec/README.md
new file mode 100644
index 000000000..b367383a5
--- /dev/null
+++ b/spec/README.md
@@ -0,0 +1,17 @@
+# Elafros API spec
+
+This directory contains the specification of the Elafros API, which is implemented in
+[`pkg/apis/ela/v1alpha1`](/pkg/apis/ela/v1alpha1) and verified via [the
+conformance tests](/test/conformance).
+
+**Updates to this spec should include a corresponding change to [the
+API implementation](/pkg/apis/ela/v1alpha1) and [the conformance
+tests](/test/conformance).** ([#780](https://github.com/elafros/elafros/issues/780))
+
+Docs in this directory:
+
+* [Motivation and goals](motivation.md)
+* [Resource type overview](overview.md)
+* [Elafros API spec](spec.md)
+* [Error conditions and reporting](errors.md)
+* [Sample API usage](normative_examples.md)
diff --git a/spec/motivation.md b/spec/motivation.md
index 573e6da9b..26a846e8a 100644
--- a/spec/motivation.md
+++ b/spec/motivation.md
@@ -1,3 +1,5 @@
+# Motivation
+
 The goal of the Elafros project is to provide a common toolkit and API
 framework for serverless workloads.
 
diff --git a/spec/spec.md b/spec/spec.md
index fdc38fe91..784c28877 100644
--- a/spec/spec.md
+++ b/spec/spec.md
@@ -1,3 +1,8 @@
+# Elafros API spec
+
+This file contains the [resource paths](#resource-paths) and [yaml
+schemas](#resource-yaml-definitions) that make up the Elafros API.
+
 ## Resource Paths
 
 Resource paths in the Elafros API have the following standard k8s form:
@@ -29,13 +34,13 @@ prod.my-service.default.mydomain.com
 ```
 
 
-# Resource YAML Definitions
+## Resource YAML Definitions
 
 YAMLs for the Elafros API resources are described below, describing the
 basic k8s structure: metadata, spec and status, along with comments on
 specific fields.
 
-## Route
+### Route
 
 For a high-level description of Routes,
 [see the overview](overview.md#route).
@@ -92,7 +97,7 @@ status:
 ```
 
 
-## Configuration
+### Configuration
 
 For a high-level description of Configurations,
 [see the overview](overview.md#configuration).
@@ -196,7 +201,7 @@ status:
 ```
 
 
-## Revision
+### Revision
 
 For a high-level description of Revisions,
 [see the overview](overview.md#revision).