diff --git a/DOCS.md b/DOCS.md
index ba65707..0e15ae1 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -72,6 +72,8 @@ Maybe this should be more ergonomic. I haven't tried this in a real project so I
 
 ## Top-Level Lexicon Types
 
+In TypeSpec, top-level definitions are called [Models](https://typespec.io/docs/language-basics/models/). So you'll see `model Foo { }` used for almost everything, but with different decorators that make its purpose more conrete.
+
 ### Record
 
 ```typescript
@@ -161,7 +163,7 @@ namespace com.example.subscribeRecords {
 
 ## Inline vs Definitions
 
-**By default, models become separate defs.** Use `@inline` to prevent this:
+**By default, all TypeSpec `model`s become separate Lexicon `defs`.** Use `@inline` to prevent this:
 
 ```typescript
 // Without @inline - becomes separate def "statusEnum"
@@ -182,7 +184,7 @@ Use `@inline` when you want the type directly embedded rather than referenced.
 
 ## Optional vs Required Fields
 
-**In lexicons, optional fields are the norm.** Required fields are discouraged and need explicit `@required`:
+**In lexicons, optional fields are the norm.** Required fields are discouraged and thus need explicit `@required`:
 
 ```typescript
 model Post {
@@ -203,6 +205,8 @@ model Post {
 }
 ```
 
+(TypeSpec doesn't require this but I figured we want to make it extra hard to accidentally make a required field.)
+
 ## Primitive Types
 
 | TypeSpec | Lexicon JSON |