diff --git a/DOCS.md b/DOCS.md
index a56eeab..60952da 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -236,9 +236,9 @@ This becomes a fully qualified reference to another Lexicon:
 
 This works across files too—just remember to `import` the file with the definition.
 
-### External Stubs
+### External References
 
-If you don't have TypeSpec definitions for external Lexicons, you can stub them out:
+If you don't have TypeSpec definitions for external Lexicons, you can stub them out using the `@external` decorator:
 
 ```typescript
 import "@typelex/emitter";
@@ -249,13 +249,16 @@ namespace app.bsky.actor.profile {
   }
 }
 
-// Empty stub (like .d.ts in TypeScript)
+// External stub (like .d.ts in TypeScript)
+@external
 namespace com.atproto.label.defs {
   model SelfLabels { }
 }
 ```
 
-You could collect stubs in one file and import them:
+The `@external` decorator tells the emitter to skip JSON output for that namespace. This is useful when referencing definitions from other Lexicons that you don't want to re-emit.
+
+You could collect external stubs in one file and import them:
 
 ```typescript
 import "@typelex/emitter";
@@ -268,7 +271,24 @@ namespace app.bsky.actor.profile {
 }
 ```
 
-You'll want to replace the stubbed lexicons in the output folder with their real JSON before running codegen.
+Then in `atproto-stubs.tsp`:
+
+```typescript
+import "@typelex/emitter";
+
+@external
+namespace com.atproto.label.defs {
+  model SelfLabels { }
+}
+
+@external
+namespace com.atproto.repo.defs {
+  model StrongRef { }
+}
+// ... more stubs
+```
+
+You'll want to ensure the real JSON for external Lexicons is available before running codegen.
 
 ### Inline Models