diff --git a/DOCS.md b/DOCS.md
index 86bf822..b0ed7ad 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -41,6 +41,8 @@ namespace com.example.defs {
 
 Use `/** */` doc comments for descriptions (or `@doc()` decorator as alternative).
 
+## Reserved Words
+
 Use backticks for TypeScript/TypeSpec reserved words:
 
 ```typescript
@@ -49,11 +51,70 @@ namespace app.bsky.feed.post.`record` {
 }
 ```
 
-The first namespace in the file will be turned into JSON. However, you can put more of them in the same file (if you want to reference them).
+## Many Lexicons in One File
+
+Multiple namespaces can be defined in one file:
+
+```typescript
+import "@typelex/emitter";
+
+namespace com.example.foo {
+  @rec("tid")
+  model Main {
+    bar?:  com.example.bar.Main
+  }
+}
+
+namespace com.example.bar {
+  model Main {
+    @maxGraphemes(1)
+    bla?: string;
+  }
+}
+```
+
+This single `.tsp` file will turn into two Lexicon files in the output folder:
+
+```
+- com/example/foo.json
+- com/example/bar.json
+```
+
+You can see this in action in the Playground, where every example is written as a single input file. For example, [this `app.bsky.actor.profile` example](https://playground.typelex.org/?sample=app.bsky.actor.profile) "spits out" multiple outputs like `app/bsky/actor/profile.json`, `com/atproto/label/defs.json`, and so on, which you can see in the right pane.
 
 ## Dependencies
 
-You can `import` other `.tsp` files.
+You can `import` other `.tsp` files. This lets you avoid defining the same thing many times if you want to refer to it from many files.
+
+For example:
+
+```typescript
+// main.tsp
+
+import "@typelex/emitter";
+import "./bar.tsp";
+
+namespace com.example.foo {
+  @rec("tid")
+  model Main {
+    bar?:  com.example.bar.Main
+  }
+}
+````
+
+```typescript
+// bar.tsp
+namespace com.example.bar {
+  model Main {
+    @maxGraphemes(1)
+    bla?: string;
+  }
+}
+````
+
+It doesn't matter how you split input into files. The output structure is only determined by namespaces.
+
+## Stubs
 
 For now, we're assuming you write everything in TypeSpec. You can grab common Lexicons from the [Playground](https://playground.typelex.org/). However, if you just want a ref, you could stub out any external Lexicon, like this: