docs

DOCS.md

···
 
 ## Introduction
 
-### What's TypeSpec?
-
-[TypeSpec](https://typespec.io/) is a TypeScript-like language for writing schemas for data and API calls.
-
-TypeSpec offers flexible syntax for describing schemas, as well as the tooling for it (like LSP), but it doesn't specify the semantics or the output format. It can target different output formats via *emitters*. For example, there's a [JSON Schema emitter](https://typespec.io/docs/emitters/json-schema/reference/) and a [Protobuf emitter](https://typespec.io/docs/emitters/protobuf/reference/) for TypeSpec. Emitters determine the output format. Emitters can define or restrict the available built-in types. Emitters can also define their own *decorators* that attach to different pieces of syntax.
-
 ### What's Lexicon?
 
-[Lexicon](https://atproto.com/specs/lexicon) is a schema format used by [AT](https://atproto.com/) applications.
-
-Here is a small Lexicon schema defining an `app.bsky.bookmark.defs` Lexicon containing a `listItemView` definition, which describes an `object` with a required `uri` property of type `at-uri`:
+[Lexicon](https://atproto.com/specs/lexicon) is a schema format used by [AT](https://atproto.com/) applications. Here's a small example:
 
 ```json
 {
···
 }
 ```
 
-You would then generate code from this schema that takes care of parsing and validating a piece of data of that shape, as well as the type definitions (e.g. for Go or TypeScript).
+This schema is then used to generate code for parsing of these objects, their validation, and their types.
 
-### What's typelex?
+### What's TypeSpec?
 
-Typelex is a TypeSpec emitter that targets AT Lexicon as the output format. As such, it adds built-in Lexicon data types and a few decorators to control the structure of the Lexicon output.
+[TypeSpec](https://typespec.io/) is a TypeScript-like language for writing schemas for data and API calls. It offers flexible syntax and tooling (like LSP), but doesn't specify output format—that's what *emitters* do. For example, there's a [JSON Schema emitter](https://typespec.io/docs/emitters/json-schema/reference/) and a [Protobuf emitter](https://typespec.io/docs/emitters/protobuf/reference/). Emitters can define built-in types and *decorators* for different pieces of syntax.
+
+### What's typelex?
 
-Here's the above Lexicon written in TypeSpec (with the typelex emitter):
+Typelex is a TypeSpec emitter targeting Lexicon. Here's the same schema in TypeSpec:
 
 ```typescript
 import "@typelex/emitter";
···
 }
 ```
 
-Then you run the compiler, and it generates the Lexicon JSON for you.
+Run the compiler, and it generates Lexicon JSON for you.
 
-It is important to note that the JSON format is in which you'll publish your Lexicons. Typelex only exists for authoring convenience and does not aim to supplant or replace Lexicon JSON itself. Think of it as a "CoffeeScript for Lexicon" (however terrible that may be).
+The JSON is what you'll publish—typelex just makes authoring easier. Think of it as "CoffeeScript for Lexicon" (however terrible that may be).
 
-Typelex tries to stay faithful to both TypeSpec idioms and Lexicon concepts, which makes it a bit confusing and sometimes not elegant. Since we can't add new keywords to TypeSpec, often there's a decorator that fills the need. For example, you'll have to write `@procedure op` whereas ideally there would just be a `procedure` keyword, or you'll have to write `model` for something that Lexicon calls a "def". In essence, you have to learn both Lexicon *and* TypeSpec. It is a good idea to scan through the [TypeSpec language overview](https://typespec.io/docs/language-basics/overview/) to get a feel for it.
+Typelex tries to stay faithful to both TypeSpec idioms and Lexicon concepts, which is a tricky balance. Since we can't add keywords to TypeSpec, decorators fill the gaps—you'll write `@procedure op` instead of `procedure`, or `model` for what Lexicon calls a "def". One downside of this approach is you'll need to learn both Lexicon *and* TypeSpec to know what you're doing. Scan the [TypeSpec language overview](https://typespec.io/docs/language-basics/overview/) to get a feel for it, it isn't much.
 
-Personally, I find JSON Lexicons difficult to read and to author so the tradeoff is worth it for me.
+Personally, I find JSON Lexicons hard to read and author, so the tradeoff works for me.
 
 ### Playground
 
 [Open Playground](https://playground.typelex.org/) to play with a bunch of lexicons and to see how typelex code translates to Lexicon JSON. If you already know Lexicon, you can learn the syntax by just opening the Lexicons you're familiar with.
 
 ## Quick Start
-
-Let's dive into some common patterns and see how to write them.
 
 ### Namespaces
 
-A namespace corresponds to a Lexicon output file. For example:
+A namespace corresponds to a Lexicon file:
 
 ```typescript
 import "@typelex/emitter";
···
 }
 ```
 
-will emit `app/bsky/feed/defs.json`:
+This emits `app/bsky/feed/defs.json`:
 
 ```json
 {
   "lexicon": 1,
   "id": "app.bsky.feed.defs",
-  // ...
+  "defs": { ... }
 }
 ```
 
-You can [try it in the playground](https://playground.typelex.org/?c=aW1wb3J0ICJAdHlwZWxleC9lbWl0dGVyIjsKCm5hbWVzcGFjZSBhcHAuYnNreS5mZWVkLmRlZnMgewogIG1vZGVsIFBvc3RWaWV3xRMgIHJlcGx5Q291bnQ%2FOiBpbnRlZ2VyO8gab3N01RtsaWtl0xl9Cn0K&e=%40typelex%2Femitter&options=%7B%7D&vs=%7B%7D).
+[Try it in the playground](https://playground.typelex.org/?c=aW1wb3J0ICJAdHlwZWxleC9lbWl0dGVyIjsKCm5hbWVzcGFjZSBhcHAuYnNreS5mZWVkLmRlZnMgewogIG1vZGVsIFBvc3RWaWV3xRMgIHJlcGx5Q291bnQ%2FOiBpbnRlZ2VyO8gab3N01RtsaWtl0xl9Cn0K&e=%40typelex%2Femitter&options=%7B%7D&vs=%7B%7D).
 
-### Reserved Words
+Use backticks for reserved words:
 
-Use backticks for TypeScript/TypeSpec reserved words:
+```typescript
+import "@typelex/emitter";
 
-```typescript
 namespace app.bsky.feed.post.`record` { }
-
 namespace `pub`.blocks.blockquote { }
 ```
 
-### Multiple Namespaces in One File
-
-Multiple namespaces can be defined in one file:
+You can define multiple namespaces in one file:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace com.example.foo {
-  @rec("tid")
-  model Main {
-    bar?: com.example.bar.Main
-  }
+  model Main { /* ... */ }
 }
 
 namespace com.example.bar {
-  model Main {
-    @maxGraphemes(1)
-    bla?: string;
-  }
+  model Main { /* ... */ }
 }
 ```
 
-This single `.tsp` file will emit two Lexicon files:
-
-```
-- com/example/foo.json
-- com/example/bar.json
-```
+This emits two files: `com/example/foo.json` and `com/example/bar.json`.
 
-You can `import` other `.tsp` files to avoid defining the same thing multiple times. The output structure is only determined by namespaces, not by how you split your input files.
+You can `import` other `.tsp` files to reuse definitions. Output structure is determined solely by namespaces, not by source file organization.
 
 ## Models
 
-A namespace may contain [`model`s](https://typespec.io/docs/language-basics/models/) inside. By default, **every `model` turns into a Lexicon definition** (`defs` in the Lexicon output). For example, if you have a `PostView` model defined like this:
+By default, **every `model` becomes a Lexicon definition**:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace app.bsky.feed.defs {
-  model PostView {
-    // ...
-  }
+  model PostView { /* ... */ }
+  model ViewerState { /* ... */ }
 }
 ```
 
-It will then become `postView` definition in the `defs` of this namespace's Lexicon:
+Model names convert PascalCase → camelCase:
 
 ```json
 {
-  "lexicon": 1,
   "id": "app.bsky.feed.defs",
   "defs": {
-    "postView": {
-      // ...
-    }
+    "postView": { /* ... */ },
+    "viewerState": { /* ... */ }
   }
+  // ...
 }
 ```
 
-A namespace may have multiple `model`s:
-
-```typescript
-namespace app.bsky.feed.defs {
-  model PostView {
-    // ...
-  }
+Models in the same namespace can be in separate `namespace` blocks or even different files (via [`import`](https://typespec.io/docs/language-basics/imports/)). TypeSpec bundles them all into one Lexicon file per namespace.
 
-  model ViewerState {
-    // ...
-  }
-}
-```
+### Namespace Conventions: `.defs` vs `Main`
 
-Every `model` becomes an entry in `defs`:
-
-```json
-{
-  "lexicon": 1,
-  "id": "app.bsky.feed.defs",
-  "defs": {
-    "postView": {
-      // ...
-    },
-    "viewerState": {
-      // ..
-    }
-  }
-}
-```
+By convention, a namespace must either have a `Main` model or end with `.defs`.
 
-This works even if they're declared in separate `namespace` blocks:
+Use `.defs` for a grabbag of reusable definitions:
 
 ```typescript
-namespace app.bsky.feed.defs {
-  model PostView {
-    // ...
-  }
-}
+import "@typelex/emitter";
 
 namespace app.bsky.feed.defs {
-  model ViewerState {
-    // ...
-  }
+  model PostView { /* ... */ }
+  model ViewerState { /* ... */ }
 }
 ```
 
-These blocks could even be in different files, one [`import`ing](https://typespec.io/docs/language-basics/imports/) the other.
-
-In either case, TypeSpec will find all the models inside each namespace (such as `app.bsky.feed.defs`), and bundle each namespace into a separate Lexicon file (such as `app/bsky/feed/defs.json`) with all its `defs`.
-
-### Namespace Conventions: `.defs` vs `Main`
-
-By Lexicon convention, a namespace must either have a `Main` model or end with `.defs`.
-
-You should end your namespace in `.defs` if you want a grabbag of reusable definitions:
+For a Lexicon about one main concept, add a `Main` model instead:
 
 ```typescript
-namespace app.bsky.feed.defs {
-  model PostView {
-    // ...
-  }
-
-  model ViewerState {
-    // ...
-  }
-}
-```
-
-On the other hand, if your Lexicon is about one main concept, don't add `.defs` to the namespace, and instead pick some model to be called `Main`:
+import "@typelex/emitter";
 
-```typescript
 namespace app.bsky.embed.video {
-  model Main {
-    @required
-    video: Blob<#["video/mp4"], 100000000>;
-
-    @maxItems(20)
-    captions?: Caption[];
-  }
-
-  model Caption {
-    // ...
-  }
+  model Main { /* ... */ }
+  model Caption { /* ... */ }
 }
 ```
 
-Either do one or the other, or you'll get a compile error forcing you to choose.
+Pick one or the other—the compiler will error if you don't.
 
 ### References
 
-A `model` can reference another `model` as a data type like so:
+Models can reference other models:
 
 ```typescript
+import "@typelex/emitter";
+
 namespace app.bsky.embed.video {
   model Main {
-    // A reference to the `Caption` model below:
     captions?: Caption[];
   }
-
-  model Caption {
-    // ...
-  }
+  model Caption { /* ... */ }
 }
 ```
 
-In the resulting Lexicon JSON, this becomes a `ref` to the local `#caption` def:
+This becomes a local `ref`:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "app.bsky.embed.video",
-  "defs": {
-    "main": {
-      "type": "object",
-      "properties": {
-        "captions": {
-          "type": "array",
-          "items": {
-            // A reference to the `caption` def below:
-            "type": "ref",
-            "ref": "#caption"
-          }
-        }
-      }
-    },
-    "caption": {
-      "type": "object",
-      "properties": {}
-    }
-  }
+// ...
+"captions": {
+  "type": "array",
+  "items": { "type": "ref", "ref": "#caption" }
 }
+// ...
 ```
 
-You can also reference `model`s from other namespaces:
+You can also reference models from other namespaces:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace app.bsky.actor.profile {
   model Main {
-    // A reference to the `SelfLabel` model from another Lexicon:
     labels?: (com.atproto.label.defs.SelfLabels | unknown);
   }
 }
 
 namespace com.atproto.label.defs {
-  model SelfLabels {
-    // ...
-  }
+  model SelfLabels { /* ... */ }
 }
 ```
 
-This will become a fully qualified reference:
+This becomes a fully qualified reference:
 
 ```json
 // ...
···
 // ...
 ```
 
-This will work even if you move the `com.atproto.label.defs` definition to another `.tsp` file, as long as you don't forget to `import` that file.
+([See it in the Playground](https://playground.typelex.org/?c=aW1wb3J0ICJAdHlwZWxleC9lbWl0dGVyIjsKCm5hbWVzcGFjZSBhcHAuYnNreS5hY3Rvci5wcm9maWxlIHsKICBAcmVjKCJsaXRlcmFsOnNlbGYiKQogIG1vZGVsIE1haW7FJiAgZGlzcGxheU5hbWU%2FOiBzdHJpbmc7xRpsYWJlbHM%2FOiAoY29tLmF0cHJvdG8uxRYuZGVmcy5TZWxmTMUlIHwgdW5rbm93binEPH0KfewAptY%2F5QCA5gCPy0nEFSAgLy8gLi4uxko%3D&e=%40typelex%2Femitter&options=%7B%7D&vs=%7B%7D).)
 
-As you can see [in the Playground](https://playground.typelex.org/?c=aW1wb3J0ICJAdHlwZWxleC9lbWl0dGVyIjsKCm5hbWVzcGFjZSBhcHAuYnNreS5hY3Rvci5wcm9maWxlIHsKICBAcmVjKCJsaXRlcmFsOnNlbGYiKQogIG1vZGVsIE1haW7FJiAgZGlzcGxheU5hbWU%2FOiBzdHJpbmc7xRpsYWJlbHM%2FOiAoY29tLmF0cHJvdG8uxRYuZGVmcy5TZWxmTMUlIHwgdW5rbm93binEPH0KfewAptY%2F5QCA5gCPy0nEFSAgLy8gLi4uxko%3D&e=%40typelex%2Femitter&options=%7B%7D&vs=%7B%7D), this actually emits *two Lexicon files* since there are two separate namespaces being declared.
-
-This makes sense if both definitions are yours, but what if you just want to *refer to* someone else's Lexicon?
+This works across files too—just remember to `import` the file with the definition.
 
 ### External Stubs
 
-The easiest way to use someone else's Lexicon is to import its definition, assuming it's also written in TypeSpec.
-
-```typescript
-import "../atproto.tsp"
-```
-
-In practice, you probably won't have all the definitions of the Lexicons you depend on written in TypeSpec. However, you can **stub out any definition you depend on**:
+If you don't have TypeSpec definitions for external Lexicons, you can stub them out:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace app.bsky.actor.profile {
   model Main {
-    // A reference to a stub
     labels?: (com.atproto.label.defs.SelfLabels | unknown);
   }
 }
 
-// This is a stub! It's fine for it to be empty.
-// Think of it similarly to a .d.ts definition in TypeScript.
+// Empty stub (like .d.ts in TypeScript)
 namespace com.atproto.label.defs {
   model SelfLabels { }
 }
 ```
 
-You could place stubs together and import them from the definitions that need them, and then ignore the (incomplete) Lexicon JSON output for those stubs (since it's going to be empty).
+You could collect stubs in one file and import them:
 
 ```typescript
 import "@typelex/emitter";
-import "../atproto-stubs.tsp"; // All your stubs here
+import "../atproto-stubs.tsp";
 
 namespace app.bsky.actor.profile {
   model Main {
-    // A reference to a stub
     labels?: (com.atproto.label.defs.SelfLabels | unknown);
   }
 }
 ```
 
-I'm not sure which organizational patterns work best in practice. Try different things and let me know.
+You'll want to replace the stubbed lexicons in the output folder with their real JSON before running codegen.
 
 ### Inline Models
 
-By default, every `model` becomes a top-level entry in Lexicon `defs`.
-
-This:
+By default, every `model` becomes a top-level def:
 
 ```typescript
 import "@typelex/emitter";
···
   model Main {
     captions?: Caption[];
   }
-
-  model Caption {
-    text?: string
-  }
+  model Caption { /* ... */ }
 }
 ```
 
-turns into:
-
-```json
-{
-  "lexicon": 1,
-  "id": "app.bsky.embed.video",
-  "defs": {
-    "main": {
-      // ...
-    },
-    "caption": {
-      // ...
-    }
-  }
-}
-```
+This creates two defs: `main` and `caption`.
 
-Sometimes, you might want to avoid exposing a model as its own `def`, and you just want it to be expanded inline. Put the `@inline` decorator on the `model` to force it into being inlined at every usage site:
+Use `@inline` to expand a model inline instead:
 
 ```typescript
 import "@typelex/emitter";
···
 }
 ```
 
-Then it will be inlined wherever it's being used:
+Now `Caption` is expanded inline:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "app.bsky.embed.video",
-  "defs": {
-    "main": {
-      "type": "object",
-      "properties": {
-        "captions": {
-          "type": "array",
-          "items": {
-            // That's our Caption, inlined.
-            "type": "object",
-            "properties": {
-              "text": { "type": "string" }
-            }
-          }
-        }
-      }
-    }
+// ...
+"captions": {
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": { "text": { "type": "string" } }
   }
 }
+// ...
 ```
 
-Note this means that different usages of `Caption` will have no relation to each other from the Lexicon perspective. The fact that the `Caption` abstraction exists will essentially be erased.
+Note that `Caption` won't exist as a separate def—the abstraction is erased in the output.
 
 ## Top-Level Lexicon Types
 
-In TypeSpec, definitions of things 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 concrete.
+TypeSpec uses `model` for almost everything. Decorators specify what kind of Lexicon type it becomes.
 
 ### Objects
 
-If you haven't marked your `model` with any decorator, it will be a Lexicon *object*.
+A plain `model` becomes a Lexicon object:
 
 ```typescript
+import "@typelex/emitter";
+
 namespace com.example.post {
-  model Main {
-    // ...
-  }
+  model Main { /* ... */ }
 }
 ```
 
-becomes
+Output:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "com.example.post",
-  "defs": {
-    "main": {
-      "type": "object",
-      "properties": {
-        // ...
-      }
-    }
-  }
+// ...
+"main": {
+  "type": "object",
+  "properties": { /* ... */ }
 }
+// ...
 ```
 
 ### Records
 
-Mark a `model` with a `@rec` decorator to make it a Lexicon *record*.
-
-For example:
+Use `@rec` to make a model a Lexicon record:
 
 ```typescript
-import "@typelex/emitter"; // Don't forget this import!
+import "@typelex/emitter";
 
 namespace com.example.post {
   @rec("tid")
-  model Main {
-    // ...
-  }
+  model Main { /* ... */ }
 }
 ```
 
-(Note it's `@rec` and not `@record` because unfortunately "record" is reserved in TypeSpec.)
-
-This becomes:
+Output:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "com.example.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "key": "tid",
-      "record": {
-        "type": "object",
-        "properties": {
-          // ...
-        }
-      }
-    }
-  }
+// ...
+"main": {
+  "type": "record",
+  "key": "tid",
+  "record": { "type": "object", "properties": { /* ... */ } }
 }
+// ...
 ```
 
-You can pass any [Record Key Type](https://atproto.com/specs/record-key) to `@rec`, like `@rec("nsid")`, `@rec("literal:self")`, etc.
+You can pass any [Record Key Type](https://atproto.com/specs/record-key): `@rec("tid")`, `@rec("nsid")`, `@rec("literal:self")`, etc.
+
+(It's `@rec` not `@record` because "record" is reserved in TypeSpec.)
 
 ### Queries
 
-In TypeSpec, functions are defined with [`op`](https://typespec.io/docs/language-basics/operations/) (for "operation"). Since Lexicon distinguishes *queries* and *procedures*, you need to mark an `op` with either `@query` or `@procedure`.
-
-Here is an example query:
+In TypeSpec, use [`op`](https://typespec.io/docs/language-basics/operations/) for functions. Mark with `@query` for queries:
 
 ```typescript
 import "@typelex/emitter";
 
-// examples/com/atproto/repo/getRecord.tsp
 namespace com.atproto.repo.getRecord {
   @query
   op main(
···
 }
 ```
 
-The sequential arguments to `main` are rendered as `params` in the generated JSON, while the return type becomes its `output`:
+Arguments become `parameters`, return type becomes `output`:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "com.atproto.repo.getRecord",
-  "defs": {
-    "main": {
-      "type": "query",
-      "parameters": {
-        "type": "params",
-        "properties": {
-          "repo": { /* ... */ },
-          "collection": { /* ... */ },
-          "rkey": { /* ... */ },
-          "cid": { /* ... */ }
-        },
-        "required": ["repo", "collection", "rkey"]
+// ...
+"main": {
+  "type": "query",
+  "parameters": {
+    "type": "params",
+    "properties": {
+      "repo": { /* ... */ },
+      "collection": { /* ... */ },
+      // ...
+    },
+    "required": ["repo", "collection", "rkey"]
+  },
+  "output": {
+    "encoding": "application/json",
+    "schema": {
+      "type": "object",
+      "properties": {
+        "uri": { /* ... */ },
+        "cid": { /* ... */ }
       },
-      "output": {
-        "encoding": "application/json",
-        "schema": {
-          "type": "object",
-          "properties": {
-            "uri": { /* ... */ },
-            "cid": { /* ... */ }
-          },
-          "required": ["uri"]
-        }
-      }
+      "required": ["uri"]
     }
   }
 }
+// ...
 ```
 
-Note that `encoding` is assumed to be `"application/json"`. You can override it with the `@encoding` decorator:
+`encoding` defaults to `"application/json"`. Override with `@encoding("foo/bar")` on the `op`.
 
-```typescript
-@query
-@encoding("foo/bar")
-op main(
-  // ...
-```
-
-You may also declare `errors` with the `@errors` decorator like so:
+Declare errors with `@errors`:
 
 ```typescript
 import "@typelex/emitter";
···
 namespace com.atproto.repo.getRecord {
   @query
   @errors(FooError, BarError)
-  op main(
-    // ...
-  ): {
-    // ...
-  };
+  op main(/* ... */): { /* ... */ };
 
   model FooError {}
   model BarError {}
 }
 ```
 
-If you don't like writing the output definition inline as the `main` return type, you can extract it to a separate `model`. You'll probably want to mark that model as `@inline` so it doesn't clutter the `defs`.
+You can extract the `{ /* ... */ }` output type to a separate `@inline` model if you prefer.
 
 ### Procedures
 
-Procedures are declared with `@procedure op`:
+Use `@procedure` for procedures. The first argument must be called `input`:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace com.example.createRecord {
-  /** Create a new record */
   @procedure
   op main(input: {
     @required text: string;
···
 }
 ```
 
-Note that, unlike with queries, you can't change the argument names. The first argument *must* be called `input`. It will correspond to the `input` section inside the procedure's JSON:
+Output:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "com.example.createRecord",
-  "defs": {
-    "main": {
-      "type": "procedure",
-      "description": "Create a new record",
-      "input": {
-        "encoding": "application/json",
-        "schema": {
-          "type": "object",
-          "properties": {
-            "text": { "type": "string" }
-          },
-          "required": ["text"]
-        }
+// ...
+"main": {
+  "type": "procedure",
+  "input": {
+    "encoding": "application/json",
+    "schema": {
+      "type": "object",
+      "properties": { "text": { "type": "string" } },
+      "required": ["text"]
+    }
+  },
+  "output": {
+    "encoding": "application/json",
+    "schema": {
+      "type": "object",
+      "properties": {
+        "uri": { /* ... */ },
+        "cid": { /* ... */ }
       },
-      "output": {
-        "encoding": "application/json",
-        "schema": {
-          "type": "object",
-          "properties": {
-            "uri": { /* ... */ },
-            "cid": { /* ... */  }
-          },
-          "required": ["uri", "cid"]
-        }
-      }
+      "required": ["uri", "cid"]
     }
   }
 }
-```
-
-Although this is very rarely done, procedures can also receive parameters (like queries). However, they are declared inside an optional second object argument like `@procedure op(input: {}, parameters: {})`.
-
-Use `: void` for procedures with no output:
-
-```typescript
-@procedure
-op main(input: {
-  @required uri: atUri;
-}): void;
+// ...
 ```
 
-Use `: never` with `@encoding()` for output with encoding but no schema:
+Procedures can also receive parameters (rarely used): `op main(input: {}, parameters: {})`.
 
-```typescript
-@query
-@encoding("application/json")
-op main(id?: string): never;
-```
+Use `: void` for no output, or `: never` with `@encoding()` on the `op` for output with encoding but no schema.
 
 ### Subscriptions
 
-Defining an `op` with `@subscription` gives you a subscription:
+Use `@subscription` for subscriptions:
 
 ```typescript
 import "@typelex/emitter";
···
 namespace com.atproto.sync.subscribeRepos {
   @subscription
   @errors(FutureCursor, ConsumerTooSlow)
-  op main(
-    cursor?: integer
-  ): Commit | Sync | unknown;
-
-  model Commit {
-    // ...
-  }
-
-  model Sync {
-    // ...
-  }
+  op main(cursor?: integer): Commit | Sync | unknown;
 
+  model Commit { /* ... */ }
+  model Sync { /* ... */ }
   model FutureCursor {}
   model ConsumerTooSlow {}
 }
 ```
 
-This becomes:
+Output:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "com.atproto.sync.subscribeRepos",
-  "defs": {
-    "main": {
-      "type": "subscription",
-      "parameters": {
-        "type": "params",
-        "properties": {
-          "cursor": { /* ... */ }
-        }
-      },
-      "message": {
-        "schema": {
-          "type": "union",
-          "refs": ["#commit", "#sync"]
-        }
-      },
-      "errors": [{ "name": "FutureCursor" }, { "name": "ConsumerTooSlow" }]
-    },
-    "commit": { /* ... */ },
-    "sync": { /* ... */ }
-  }
+// ...
+"main": {
+  "type": "subscription",
+  "parameters": {
+    "type": "params",
+    "properties": { "cursor": { /* ... */ } }
+  },
+  "message": {
+    "schema": {
+      "type": "union",
+      "refs": ["#commit", "#sync"]
+    }
+  },
+  "errors": [{ "name": "FutureCursor" }, { "name": "ConsumerTooSlow" }]
 }
+// ...
 ```
 
 ### Tokens
 
-Empty models marked with `@token` become token definitions:
+Use `@token` for empty token models:
 
 ```typescript
-/** Indicates spam content */
-@token
-model ReasonSpam {}
+namespace com.example.moderation.defs {
+  @token
+  model ReasonSpam {}
 
-/** Indicates policy violation */
-@token
-model ReasonViolation {}
+  @token
+  model ReasonViolation {}
 
-model Report {
-  @required reason: (ReasonSpam | ReasonViolation | unknown);
+  model Report {
+    @required reason: (ReasonSpam | ReasonViolation | unknown);
+  }
 }
 ```
 
-**Maps to:**
+Output:
+
 ```json
-{
-  "report": {
-    "properties": {
-      "reason": {
-        "type": "union",
-        "refs": ["#reasonSpam", "#reasonViolation"]
-      }
+// ...
+"reasonSpam": { "type": "token" },
+"reasonViolation": { "type": "token" },
+"report": {
+  "type": "object",
+  "properties": {
+    "reason": {
+      "type": "union",
+      "refs": ["#reasonSpam", "#reasonViolation"]
     }
   },
-  "reasonSpam": {
-    "type": "token",
-    "description": "Indicates spam content"
-  }
+  "required": ["reason"]
 }
+// ...
 ```
 
 ## Data Types
···
 Use `[]` suffix:
 
 ```typescript
-model Main {
-  /** Array of strings */
-  stringArray?: string[];
+import "@typelex/emitter";
 
-  /** Array with size constraints */
-  @minItems(1)
-  @maxItems(10)
-  limitedArray?: integer[];
+namespace com.example.arrays {
+  model Main {
+    stringArray?: string[];
 
-  /** Array of references */
-  items?: Item[];
+    @minItems(1)
+    @maxItems(10)
+    limitedArray?: integer[];
 
-  /** Array of union types */
-  mixed?: (TypeA | TypeB | unknown)[];
+    items?: Item[];
+    mixed?: (TypeA | TypeB | unknown)[];
+  }
+  // ...
 }
 ```
 
-**Maps to:** `{"type": "array", "items": {...}}`
+Output: `{ "type": "array", "items": {...} }`.
 
-**Note:** `@minItems`/`@maxItems` in TypeSpec map to `minLength`/`maxLength` in JSON.
+Note: `@minItems`/`@maxItems` map to `minLength`/`maxLength` in JSON.
 
 ### Blobs
 
 ```typescript
-model Main {
-  /** Basic blob */
-  file?: Blob;
+import "@typelex/emitter";
 
-  /** Image up to 5MB */
-  image?: Blob<#["image/*"], 5000000>;
-
-  /** Specific types up to 2MB */
-  photo?: Blob<#["image/png", "image/jpeg"], 2000000>;
+namespace com.example.blobs {
+  model Main {
+    file?: Blob;
+    image?: Blob<#["image/*"], 5000000>;
+    photo?: Blob<#["image/png", "image/jpeg"], 2000000>;
+  }
 }
 ```
 
-**Maps to:**
+Output:
+
 ```json
-{
-  "file": {"type": "blob"},
-  "image": {
-    "type": "blob",
-    "accept": ["image/*"],
-    "maxSize": 5000000
-  }
+// ...
+"image": {
+  "type": "blob",
+  "accept": ["image/*"],
+  "maxSize": 5000000
 }
+// ...
 ```
 
 ## Required and Optional Fields
 
-In Lexicon, the default is to make fields optional. Use `?:` for that:
+In Lexicon, fields are optional by default. Use `?:`:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace tools.ozone.moderation.defs {
   model SubjectStatusView {
-    subjectBlobCids?: cid[];
     subjectRepoHandle?: string;
   }
 }
 ```
 
-This becomes:
+**Think thrice before adding required fields**—you can't make them optional later.
 
-```json
-{
-  "lexicon": 1,
-  "id": "tools.ozone.moderation.defs",
-  "defs": {
-    "subjectStatusView": {
-      "type": "object",
-      "properties": {
-        "subjectBlobCids": {
-          "type": "array",
-          "items": { "type": "string", "format": "cid" }
-        },
-        "subjectRepoHandle": { "type": "string" }
-      }
-    }
-  }
-}
-```
-
-Think twice before adding a required field because you won't be able to make it optional later without violating the schema contract (and making all existing records invalid). In practice, this often means you'd have to deprecate the field and create another field, which is messy.
-
-This is why required fields need a special `@required` decorator forcing you to think twice.
+This is why `@required` is explicit:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace tools.ozone.moderation.defs {
   model SubjectStatusView {
-    subjectBlobCids?: cid[];
     subjectRepoHandle?: string;
-
     @required createdAt: datetime;
   }
 }
 ```
 
-This becomes:
+Output:
 
 ```json
 // ...
 "required": ["createdAt"]
+// ...
 ```
 
 ## Unions
 
 ### Open Unions (Recommended)
 
-In Lexicon, unions like "A or B" default to being *open*, i.e. allowing you to add C in the future.
-
-To declare an open union, write `| unknown` at the end, like `Images | Video | unknown`:
+Unions default to being *open*—allowing you to add more options later. Write `| unknown`:
 
 ```typescript
 import "@typelex/emitter";
···
     embed?: Images | Video | unknown;
   }
 
-  model Images {
-    // ...
-  }
-
-  model Video {
-    // ...
-  }
+  model Images { /* ... */ }
+  model Video { /* ... */ }
 }
 ```
 
-This produces a `union`:
+Output:
 
 ```json
-{
-  "lexicon": 1,
-  "id": "app.bsky.feed.post",
-  "defs": {
-    "main": {
-      "type": "object",
-      "properties": {
-        "embed": {
-          "type": "union",
-          "refs": ["#images", "#video"]
-        }
-      }
-    },
-    "images": { /* ... */ },
-    "video": { /* ... */ }
-  }
+// ...
+"embed": {
+  "type": "union",
+  "refs": ["#images", "#video"]
 }
+// ...
 ```
 
-Then later you can add more types to the union.
-
-You may also write the same thing with the `union` syntax instead of writing `A | B | C | unknown` directly:
+You can also use the `union` syntax to give it a name:
 
 ```typescript
+import "@typelex/emitter";
+
 namespace app.bsky.feed.post {
   model Main {
     embed?: EmbedType;
···
 
   @inline union EmbedType { Images, Video, unknown }
 
-  model Images {
-    // ...
-  }
-
-  model Video {
-    // ...
-  }
+  model Images { /* ... */ }
+  model Video { /* ... */ }
 }
 ```
 
-This is completely equivalent. The `@inline` decorator states that it doesn't become a part of your defs.
+The `@inline` prevents it from becoming a separate def in the output.
 
 ### Known Values (Open Enums)
 
-You can suggest common values but allow others:
+Suggest common values but allow others with `| string`:
 
 ```typescript
 import "@typelex/emitter";
···
 }
 ```
 
-Note the `| string` that says you may add more "known" values later.
-
-The `union` syntax also works for this:
+The `union` syntax works here too:
 
 ```typescript
 import "@typelex/emitter";
···
 }
 ```
 
-Here, `@inline` prevents creation of a `languages` top-level def. If you *do* want to make it reusable from other Lexicons, remove the `@inline` annotation and refer to `com.example.Languages` from somewhere else.
+You can remove `@inline` to make it a reusable `def` accessible from other Lexicons.
 
 ### Closed Unions and Enums (Discouraged)
 
-If you want to create a *closed* union (which are **heavily discouraged** in Lexicon), you can mark your union with a `@closed` decorator. This will let you remove the `unknown` case from it.
+**Heavily discouraged** in Lexicon.
 
-There is no shorthand notation for closed unions, so you'll have to write `@closed @inline union { A, B }`.
+Marking a `union` as `@closed` lets you remove `unknown` from the list of options:
 
 ```typescript
 import "@typelex/emitter";
 
 namespace com.atproto.repo.applyWrites {
-  @procedure
-  op main(input: {
-    @required
-    writes: WriteAction[];
-  }): {
-    // ...
-  };
+  model Main {
+    @required writes: WriteAction[];
+  }
 
   @closed // Discouraged!
   @inline
-  union WriteAction { Create, Update, Delete, }
+  union WriteAction { Create, Update, Delete }
 
-  model Create {
-    // ...
-  }
-
-  model Update {
-    // ...
-  }
-
-  model Delete {
-    // ...
-  }
+  model Create { /* ... */ }
+  model Update { /* ... */ }
+  model Delete { /* ... */ }
 }
 ```
 
-This gives you:
+Output:
 
 ```json
+// ...
 "writes": {
   "type": "array",
   "items": {
···
     "closed": true
   }
 }
+// ...
 ```
 
-You can also declare this with strings or numbers:
+With strings or numbers, this becomes a closed `enum`:
 
 ```typescript
-@closed // Discouraged!
-@inline
-union WriteAction { "create", "update", "delete" }
+import "@typelex/emitter";
+
+namespace com.atproto.repo.applyWrites {
+  model Main {
+    @required action: WriteAction;
+  }
+
+  @closed // Discouraged!
+  @inline
+  union WriteAction { "create", "update", "delete" }
+}
 ```
 
-These would become a Lexicon closed `enum`:
+Output:
 
 ```json
-"items": {
-  "type": "string",
-  "enum": ["create", "update", "delete"]
-}
+// ...
+"type": "string",
+"enum": ["create", "update", "delete"]
+// ...
 ```
 
-Avoid closed unions and closed enums if you can.
+Avoid closed unions/enums when possible.
 
 ## Constraints
 
-### String Constraints
+### Strings
 
 ```typescript
-model Main {
-  /** Byte length constraints */
-  @minLength(1)
-  @maxLength(100)
-  text?: string;
+import "@typelex/emitter";
 
-  /** Grapheme cluster length constraints */
-  @minGraphemes(1)
-  @maxGraphemes(50)
-  displayName?: string;
+namespace com.example {
+  model Main {
+    @minLength(1)
+    @maxLength(100)
+    text?: string;
+
+    @minGraphemes(1)
+    @maxGraphemes(50)
+    displayName?: string;
+  }
 }
 ```
 
-**Maps to:** `minLength`/`maxLength`, `minGraphemes`/`maxGraphemes`
+Maps to: `minLength`/`maxLength`, `minGraphemes`/`maxGraphemes`
 
-### Integer Constraints
+### Integers
 
 ```typescript
-model Main {
-  @minValue(1)
-  @maxValue(100)
-  score?: integer;
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    @minValue(1)
+    @maxValue(100)
+    score?: integer;
+  }
 }
 ```
 
-**Maps to:** `minimum`/`maximum`
+Maps to: `minimum`/`maximum`
 
-### Bytes Constraints
+### Bytes
 
 ```typescript
-model Main {
-  @minBytes(1)
-  @maxBytes(1024)
-  data?: bytes;
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    @minBytes(1)
+    @maxBytes(1024)
+    data?: bytes;
+  }
 }
 ```
 
-**Maps to:** `minLength`/`maxLength`
+Maps to: `minLength`/`maxLength`
 
-**Note:** Use `@minBytes`/`@maxBytes` in TypeSpec, but they map to `minLength`/`maxLength` in JSON.
-
-### Array Constraints
+### Arrays
 
 ```typescript
-model Main {
-  @minItems(1)
-  @maxItems(10)
-  items?: string[];
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    @minItems(1)
+    @maxItems(10)
+    items?: string[];
+  }
 }
 ```
 
-**Maps to:** `minLength`/`maxLength`
+Maps to: `minLength`/`maxLength`
 
-**Note:** Use `@minItems`/`@maxItems` in TypeSpec, but they map to `minLength`/`maxLength` in JSON.
-
-## Default and Constant Values
+## Defaults and Constants
 
 ### Defaults
 
 ```typescript
-model Main {
-  version?: integer = 1;
-  lang?: string = "en";
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    version?: integer = 1;
+    lang?: string = "en";
+  }
 }
 ```
 
-**Maps to:** `{"default": 1}`, `{"default": "en"}`
+Maps to: `{"default": 1}`, `{"default": "en"}`
 
 ### Constants
 
-Use `@readOnly` with default value:
+Use `@readOnly` with a default:
 
 ```typescript
-model Main {
-  @readOnly status?: string = "active";
+import "@typelex/emitter";
+
+namespace com.example {
+  model Main {
+    @readOnly status?: string = "active";
+  }
 }
 ```
 
-**Maps to:** `{"const": "active"}`
+Maps to: `{"const": "active"}`
 
 ## Nullable Fields
 
 Use `| null` for nullable fields:
 
 ```typescript
-model Main {
-  @required createdAt: datetime;
-  updatedAt?: datetime | null;     // can be omitted or null
-  deletedAt?: datetime;            // can only be omitted
-}
-```
+import "@typelex/emitter";
 
-**Maps to:**
-```json
-{
-  "required": ["createdAt"],
-  "nullable": ["updatedAt"],
-  "properties": { ... }
+namespace com.example {
+  model Main {
+    @required createdAt: datetime;
+    updatedAt?: datetime | null;  // can be omitted or null
+    deletedAt?: datetime;         // can only be omitted
+  }
 }
 ```
 
-## Naming Conventions
+Output:
 
-Model names convert from PascalCase to camelCase in defs:
-
-```typescript
-model StatusEnum { ... }    // becomes "statusEnum"
-model UserMetadata { ... }  // becomes "userMetadata"
-model Main { ... }          // becomes "main"
+```json
+// ...
+"required": ["createdAt"],
+"nullable": ["updatedAt"]
+// ...
 ```

packages/example/package.json

···
   "type": "module",
   "scripts": {
     "build": "pnpm run build:typelex && pnpm run build:codegen",
-    "build:typelex": "tsp compile typelex/main.tsp",
-    "build:codegen": "lex gen-server --yes ./src lexicon/app/example/*.json"
+    "build:lexicons": "tsp compile typelex/main.tsp",
+    "build:codegen": "lex gen-server --yes ./src lexicons/app/example/*.json"
   },
   "dependencies": {
     "@atproto/lex-cli": "^0.9.5",

packages/example/tspconfig.yaml

···
   - "@typelex/emitter"
 options:
   "@typelex/emitter":
-    output-dir: "./lexicon"
+    output-dir: "./lexicons"

packages/website/src/pages/index.astro

···
   - "@typelex/emitter"
 options:
   "@typelex/emitter":
-    output-dir: "./lexicon"`, 'yaml')} />
+    output-dir: "./lexicons"`, 'yaml')} />
 						</div>
 					</div>
 
···
 							<figure class="install-box" set:html={await highlightCode(`{
   "scripts": {
     // ...
-    "build:lexicon": "tsp compile typelex/main.tsp"
+    "build:lexicons": "tsp compile typelex/main.tsp"
   }
 }`, 'json')} />
 						</div>
···
 						<div class="step-number">5</div>
 						<div class="step-content">
 							<h3>Generate Lexicon files</h3>
-							<figure class="install-box" set:html={await highlightCode(`npm run build:lexicon`, 'bash')} />
+							<figure class="install-box" set:html={await highlightCode(`npm run build:lexicons`, 'bash')} />
 							<p class="step-description">Lexicon files will be generated in the <code>output-dir</code> from your <code>tspconfig.yaml</code> config.</p>
 						</div>
 					</div>