add @default, don't inline scalars unless @inline

packages/emitter/lib/decorators.tsp

···
 extern dec errors(target: unknown, ...errors: unknown[]);
 
 /**
+ * Specifies a default value for a scalar or union definition.
+ * Only valid on standalone scalar or union defs (not @inline).
+ * The value must match the underlying type (string, integer, or boolean).
+ * For unions with token refs, you can pass a model reference directly.
+ *
+ * @param value - The default value (literal or model reference for tokens)
+ *
+ * @example Scalar with default
+ * ```typespec
+ * @default("standard")
+ * scalar Mode extends string;
+ * ```
+ *
+ * @example Union with token default
+ * ```typespec
+ * @default(Inperson)
+ * union EventMode { Hybrid, Inperson, Virtual, string }
+ *
+ * @token
+ * model Inperson {}
+ * ```
+ */
+extern dec `default`(target: unknown, value: unknown);
+
+/**
  * Marks a namespace as external, preventing it from emitting JSON output.
  * This decorator can only be applied to namespaces.
  * Useful for importing definitions from other lexicons without re-emitting them.

packages/emitter/src/decorators.ts

···
 const maxBytesKey = Symbol("maxBytes");
 const minBytesKey = Symbol("minBytes");
 const externalKey = Symbol("external");
+const defaultKey = Symbol("default");
 
 /**
  * @maxBytes decorator for maximum length of bytes type
···
 
 export function isReadOnly(program: Program, target: Type): boolean {
   return program.stateSet(readOnlyKey).has(target);
+}
+
+/**
+ * @default decorator for setting default values on scalars and unions
+ * The value can be a literal (string, number, boolean) or a model reference for tokens
+ */
+export function $default(context: DecoratorContext, target: Type, value: any) {
+  // Just store the raw value - let the emitter handle unwrapping and validation
+  context.program.stateMap(defaultKey).set(target, value);
+}
+
+export function getDefault(
+  program: Program,
+  target: Type,
+): any | undefined {
+  return program.stateMap(defaultKey).get(target);
 }
 
 /**

packages/emitter/src/emitter.ts

···
   getMaxBytes,
   getMinBytes,
   isExternal,
+  getDefault,
 } from "./decorators.js";
 
 export interface EmitterOptions {
···
     private program: Program,
     private options: EmitterOptions,
   ) {}
+
+  /**
+   * Process the raw default value from the decorator, unwrapping TypeSpec value objects
+   * and returning either a primitive (string, number, boolean) or a Type (for model references)
+   */
+  private processDefaultValue(rawValue: any): string | number | boolean | Type | undefined {
+    if (rawValue === undefined) return undefined;
+
+    // TypeSpec may wrap values - check if this is a value object first
+    if (rawValue && typeof rawValue === 'object' && rawValue.valueKind) {
+      if (rawValue.valueKind === "StringValue") {
+        return rawValue.value;
+      } else if (rawValue.valueKind === "NumericValue" || rawValue.valueKind === "NumberValue") {
+        return rawValue.value;
+      } else if (rawValue.valueKind === "BooleanValue") {
+        return rawValue.value;
+      }
+      return undefined; // Unsupported valueKind
+    }
+
+    // Check if it's a Type object (Model, String, Number, Boolean literals)
+    if (rawValue && typeof rawValue === 'object' && rawValue.kind) {
+      if (rawValue.kind === "String") {
+        return (rawValue as StringLiteral).value;
+      } else if (rawValue.kind === "Number") {
+        return (rawValue as NumericLiteral).value;
+      } else if (rawValue.kind === "Boolean") {
+        return (rawValue as BooleanLiteral).value;
+      } else if (rawValue.kind === "Model") {
+        // Return the model itself for token references
+        return rawValue as Model;
+      }
+      return undefined; // Unsupported kind
+    }
+
+    // Direct primitive value
+    if (typeof rawValue === 'string' || typeof rawValue === 'number' || typeof rawValue === 'boolean') {
+      return rawValue;
+    }
+
+    return undefined;
+  }
 
   async emit() {
     const globalNs = this.program.getGlobalNamespaceType();
···
   }
 
   private addScalarToDefs(lexicon: LexiconDoc, scalar: Scalar) {
+    // Only skip if the scalar itself is in TypeSpec namespace (built-in scalars)
     if (scalar.namespace?.name === "TypeSpec") return;
-    if (scalar.baseScalar?.namespace?.name === "TypeSpec") return;
 
     // Skip @inline scalars - they should be inlined, not defined separately
     if (isInline(this.program, scalar)) {
···
     const scalarDef = this.scalarToLexiconPrimitive(scalar, undefined);
     if (scalarDef) {
       const description = getDoc(this.program, scalar);
-      lexicon.defs[defName] = { ...scalarDef, description } as LexUserType;
+
+      // Apply @default decorator if present
+      const rawDefault = getDefault(this.program, scalar);
+      const defaultValue = this.processDefaultValue(rawDefault);
+      let defWithDefault: any = { ...scalarDef };
+
+      if (defaultValue !== undefined) {
+        // Check if it's a Type (model reference for tokens)
+        if (typeof defaultValue === 'object' && 'kind' in defaultValue) {
+          // For model references, we need to resolve to NSID
+          // This shouldn't happen for scalars, only unions support token refs
+          this.program.reportDiagnostic({
+            code: "invalid-default-on-scalar",
+            severity: "error",
+            message: "@default on scalars must be a literal value (string, number, or boolean), not a model reference",
+            target: scalar,
+          });
+        } else {
+          // Validate that the default value matches the type
+          this.assertValidValueForType(scalarDef.type, defaultValue, scalar);
+          defWithDefault = { ...defWithDefault, default: defaultValue };
+        }
+      }
+
+      // Apply integer constraints for standalone scalar defs
+      if (scalarDef.type === "integer") {
+        const minValue = getMinValue(this.program, scalar);
+        if (minValue !== undefined) {
+          (defWithDefault as any).minimum = minValue;
+        }
+        const maxValue = getMaxValue(this.program, scalar);
+        if (maxValue !== undefined) {
+          (defWithDefault as any).maximum = maxValue;
+        }
+      }
+
+      lexicon.defs[defName] = { ...defWithDefault, description } as LexUserType;
     }
   }
 
···
     if (unionDef.type === "string" && (unionDef.knownValues || unionDef.enum)) {
       const defName = name.charAt(0).toLowerCase() + name.slice(1);
       const description = getDoc(this.program, union);
-      lexicon.defs[defName] = { ...unionDef, description };
+
+      // Apply @default decorator if present
+      const rawDefault = getDefault(this.program, union);
+      const defaultValue = this.processDefaultValue(rawDefault);
+      let defWithDefault: any = { ...unionDef };
+
+      if (defaultValue !== undefined) {
+        // Check if it's a Type (model reference for tokens)
+        if (typeof defaultValue === 'object' && 'kind' in defaultValue) {
+          // Resolve the model reference to its NSID
+          const tokenModel = defaultValue as Model;
+          const tokenRef = this.getModelReference(tokenModel, true); // fullyQualified=true
+          if (tokenRef) {
+            defWithDefault = { ...defWithDefault, default: tokenRef };
+          } else {
+            this.program.reportDiagnostic({
+              code: "invalid-default-token",
+              severity: "error",
+              message: "@default value must be a valid token model reference",
+              target: union,
+            });
+          }
+        } else {
+          // Literal value - validate it matches the union type
+          if (typeof defaultValue !== "string") {
+            this.program.reportDiagnostic({
+              code: "invalid-default-value-type",
+              severity: "error",
+              message: `Default value type mismatch: expected string, got ${typeof defaultValue}`,
+              target: union,
+            });
+          } else {
+            defWithDefault = { ...defWithDefault, default: defaultValue };
+          }
+        }
+      }
+
+      lexicon.defs[defName] = { ...defWithDefault, description };
     } else if (unionDef.type === "union") {
       this.program.reportDiagnostic({
         code: "union-refs-not-allowed-as-def",
···
           `Use @inline to inline them at usage sites, use @token models for known values, or use string literals.`,
         target: union,
       });
+    } else if (unionDef.type === "integer" && (unionDef as any).enum) {
+      // Integer enums can also be defs
+      const defName = name.charAt(0).toLowerCase() + name.slice(1);
+      const description = getDoc(this.program, union);
+
+      // Apply @default decorator if present
+      const rawDefault = getDefault(this.program, union);
+      const defaultValue = this.processDefaultValue(rawDefault);
+      let defWithDefault = { ...unionDef };
+
+      if (defaultValue !== undefined) {
+        if (typeof defaultValue === "number") {
+          defWithDefault = { ...defWithDefault, default: defaultValue };
+        } else {
+          this.program.reportDiagnostic({
+            code: "invalid-default-value-type",
+            severity: "error",
+            message: `Default value type mismatch: expected integer, got ${typeof defaultValue}`,
+            target: union,
+          });
+        }
+      }
+
+      lexicon.defs[defName] = { ...defWithDefault, description };
     }
   }
 
···
     prop?: ModelProperty,
     propDesc?: string,
   ): LexObjectProperty | null {
+    // Check if this scalar should be referenced instead of inlined
+    const scalarRef = this.getScalarReference(scalar);
+    if (scalarRef) {
+      // Check if property has a default value that would conflict with the scalar's @default
+      if (prop?.defaultValue !== undefined) {
+        const scalarDefaultRaw = getDefault(this.program, scalar);
+        const scalarDefault = this.processDefaultValue(scalarDefaultRaw);
+        const propDefault = serializeValueAsJson(this.program, prop.defaultValue, prop);
+
+        // If the scalar has a different default, or if the property has a default but the scalar doesn't, error
+        if (scalarDefault !== propDefault) {
+          this.program.reportDiagnostic({
+            code: "conflicting-defaults",
+            severity: "error",
+            message: scalarDefault !== undefined
+              ? `Property default value conflicts with scalar's @default decorator. The scalar "${scalar.name}" has @default(${JSON.stringify(scalarDefault)}) but property has default value ${JSON.stringify(propDefault)}. Either remove the property default, mark the scalar @inline, or make the defaults match.`
+              : `Property has a default value but the referenced scalar "${scalar.name}" does not. Either add @default to the scalar, mark it @inline to allow property-level defaults, or remove the property default.`,
+            target: prop,
+          });
+        }
+      }
+
+      return { type: "ref" as const, ref: scalarRef, description: propDesc };
+    }
+
+    // Inline the scalar
     const primitive = this.scalarToLexiconPrimitive(scalar, prop);
     if (!primitive) return null;
 
···
     if (!isDefining) {
       const unionRef = this.getUnionReference(unionType);
       if (unionRef) {
+        // Check if property has a default value that would conflict with the union's @default
+        if (prop?.defaultValue !== undefined) {
+          const unionDefaultRaw = getDefault(this.program, unionType);
+          const unionDefault = this.processDefaultValue(unionDefaultRaw);
+          const propDefault = serializeValueAsJson(this.program, prop.defaultValue, prop);
+
+          // For union defaults that are model references, we need to resolve them for comparison
+          let resolvedUnionDefault: string | number | boolean | undefined = unionDefault as any;
+          if (unionDefault && typeof unionDefault === 'object' && 'kind' in unionDefault && unionDefault.kind === 'Model') {
+            const ref = this.getModelReference(unionDefault as Model, true);
+            resolvedUnionDefault = ref || undefined;
+          }
+
+          // If the union has a different default, or if the property has a default but the union doesn't, error
+          if (resolvedUnionDefault !== propDefault) {
+            this.program.reportDiagnostic({
+              code: "conflicting-defaults",
+              severity: "error",
+              message: unionDefault !== undefined
+                ? `Property default value conflicts with union's @default decorator. The union "${unionType.name}" has @default(${JSON.stringify(resolvedUnionDefault)}) but property has default value ${JSON.stringify(propDefault)}. Either remove the property default, mark the union @inline, or make the defaults match.`
+                : `Property has a default value but the referenced union "${unionType.name}" does not. Either add @default to the union, mark it @inline to allow property-level defaults, or remove the property default.`,
+              target: prop,
+            });
+          }
+        }
+
         return { type: "ref" as const, ref: unionRef, description: propDesc };
       }
     }
···
     // Check if this scalar (or its base) is bytes type
     if (this.isScalarOfType(scalar, "bytes")) {
       const byteDef: LexBytes = { type: "bytes" };
-      const target = prop || scalar;
 
-      const minLength = getMinBytes(this.program, target);
+      // Check scalar first for its own constraints, then property overrides
+      const minLength = getMinBytes(this.program, scalar) ?? (prop ? getMinBytes(this.program, prop) : undefined);
       if (minLength !== undefined) {
         byteDef.minLength = minLength;
       }
 
-      const maxLength = getMaxBytes(this.program, target);
+      const maxLength = getMaxBytes(this.program, scalar) ?? (prop ? getMaxBytes(this.program, prop) : undefined);
       if (maxLength !== undefined) {
         byteDef.maxLength = maxLength;
       }
···
 
     // Apply string constraints
     if (primitive.type === "string") {
-      const target = prop || scalar;
-      const maxLength = getMaxLength(this.program, target);
+      // Check scalar first for its own constraints, then property overrides
+      const maxLength = getMaxLength(this.program, scalar) ?? (prop ? getMaxLength(this.program, prop) : undefined);
       if (maxLength !== undefined) {
         primitive.maxLength = maxLength;
       }
-      const minLength = getMinLength(this.program, target);
+      const minLength = getMinLength(this.program, scalar) ?? (prop ? getMinLength(this.program, prop) : undefined);
       if (minLength !== undefined) {
         primitive.minLength = minLength;
       }
-      const maxGraphemes = getMaxGraphemes(this.program, target);
+      const maxGraphemes = getMaxGraphemes(this.program, scalar) ?? (prop ? getMaxGraphemes(this.program, prop) : undefined);
       if (maxGraphemes !== undefined) {
         primitive.maxGraphemes = maxGraphemes;
       }
-      const minGraphemes = getMinGraphemes(this.program, target);
+      const minGraphemes = getMinGraphemes(this.program, scalar) ?? (prop ? getMinGraphemes(this.program, prop) : undefined);
       if (minGraphemes !== undefined) {
         primitive.minGraphemes = minGraphemes;
       }
     }
 
     // Apply numeric constraints
-    if (prop && primitive.type === "integer") {
-      const minValue = getMinValue(this.program, prop);
+    if (primitive.type === "integer") {
+      // Check scalar first for its own constraints, then property overrides
+      const minValue = getMinValue(this.program, scalar) ?? (prop ? getMinValue(this.program, prop) : undefined);
       if (minValue !== undefined) {
         primitive.minimum = minValue;
       }
-      const maxValue = getMaxValue(this.program, prop);
+      const maxValue = getMaxValue(this.program, scalar) ?? (prop ? getMaxValue(this.program, prop) : undefined);
       if (maxValue !== undefined) {
         primitive.maximum = maxValue;
       }
···
   private assertValidValueForType(
     primitiveType: string,
     value: unknown,
-    prop: ModelProperty,
+    target: ModelProperty | Scalar | Union,
   ): void {
     const valid =
       (primitiveType === "boolean" && typeof value === "boolean") ||
···
         code: "invalid-default-value-type",
         severity: "error",
         message: `Default value type mismatch: expected ${primitiveType}, got ${typeof value}`,
-        target: prop,
+        target: target,
       });
     }
   }
···
 
   private getUnionReference(union: Union): string | null {
     return this.getReference(union, union.name, union.namespace);
+  }
+
+  private getScalarReference(scalar: Scalar): string | null {
+    // Built-in TypeSpec scalars (string, integer, boolean themselves) should not be referenced
+    if (scalar.namespace?.name === "TypeSpec") return null;
+
+    // @inline scalars should be inlined, not referenced
+    if (isInline(this.program, scalar)) return null;
+
+    // Scalars without names or namespace can't be referenced
+    if (!scalar.name || !scalar.namespace) return null;
+
+    const defName = scalar.name.charAt(0).toLowerCase() + scalar.name.slice(1);
+    const namespaceName = getNamespaceFullName(scalar.namespace);
+    if (!namespaceName) return null;
+
+    // Local reference (same namespace) - use short ref
+    if (
+      this.currentLexiconId === namespaceName ||
+      this.currentLexiconId === `${namespaceName}.defs`
+    ) {
+      return `#${defName}`;
+    }
+
+    // Cross-namespace reference
+    return `${namespaceName}#${defName}`;
   }
 
   private modelToLexiconArray(

packages/emitter/src/tsp-index.ts

···
   $maxBytes,
   $minBytes,
   $external,
+  $default,
 } from "./decorators.js";
 
 /** @internal */
···
     maxBytes: $maxBytes,
     minBytes: $minBytes,
     external: $external,
+    default: $default,
   },
 };

packages/emitter/test/integration/atproto/input/app/bsky/actor/defs.tsp

···
     prioritizeFollowedUsers?: boolean;
   }
 
+  @inline
   @maxLength(640)
   @maxGraphemes(64)
   scalar InterestTag extends string;
···
     @required did: did;
   }
 
+  @inline
   @maxLength(100)
   scalar NudgeToken extends string;
 

packages/emitter/test/spec/basic/input/com/example/scalarDefaults.tsp

···
+import "@typelex/emitter";
+
+namespace com.example.scalarDefaults {
+  /** Test default decorator on scalars */
+  model Main {
+    /** Uses string scalar with default */
+    mode?: Mode;
+
+    /** Uses integer scalar with default */
+    limit?: Limit;
+
+    /** Uses boolean scalar with default */
+    enabled?: Enabled;
+  }
+
+  /** A string type with a default value */
+  @default("standard")
+  @maxLength(50)
+  scalar Mode extends string;
+
+  /** An integer type with a default value */
+  @default(50)
+  @minValue(1)
+  @maxValue(100)
+  scalar Limit extends integer;
+
+  /** A boolean type with a default value */
+  @default(true)
+  scalar Enabled extends boolean;
+}

packages/emitter/test/spec/basic/input/com/example/scalarDefs.tsp

···
+import "@typelex/emitter";
+
+namespace com.example.scalarDefs {
+  /** Scalar defs should create standalone defs like models and unions */
+  model Main {
+    /** Uses a custom string scalar with constraints */
+    tag?: Tag;
+
+    /** Uses a custom integer scalar with constraints */
+    count?: Count;
+  }
+
+  /** A custom string type with length constraints */
+  @maxLength(100)
+  @maxGraphemes(50)
+  scalar Tag extends string;
+
+  /** A custom integer type with value constraints */
+  @minValue(1)
+  @maxValue(100)
+  scalar Count extends integer;
+}

packages/emitter/test/spec/basic/input/com/example/scalarInline.tsp

···
+import "@typelex/emitter";
+
+namespace com.example.scalarInline {
+  /** Test inline decorator on scalars */
+  model Main {
+    /** Inline scalar - should not create a def */
+    tag?: Tag;
+
+    /** Non-inline scalar - should create a def */
+    category?: Category;
+  }
+
+  /** An inline scalar should be inlined at usage sites */
+  @inline
+  @maxLength(50)
+  @maxGraphemes(25)
+  scalar Tag extends string;
+
+  /** A regular scalar should create a standalone def */
+  @maxLength(100)
+  scalar Category extends string;
+}

packages/emitter/test/spec/basic/input/com/example/unionDefaults.tsp

···
+import "@typelex/emitter";
+
+namespace com.example.unionDefaults {
+  /** Test default decorator on unions */
+  model Main {
+    /** Union with token refs and default */
+    eventMode?: EventMode;
+
+    /** Union with string literals and default */
+    sortOrder?: SortOrder;
+
+    /** Union with integer literals and default */
+    priority?: Priority;
+  }
+
+  /** Union of tokens with default pointing to a token */
+  @default(Inperson)
+  union EventMode {
+    Hybrid,
+    Inperson,
+    Virtual,
+    string,
+  }
+
+  /** A hybrid event */
+  @token
+  model Hybrid {}
+
+  /** An in-person event */
+  @token
+  model Inperson {}
+
+  /** A virtual event */
+  @token
+  model Virtual {}
+
+  /** Union of string literals with default */
+  @default("asc")
+  union SortOrder {
+    "asc",
+    "desc",
+    string,
+  }
+
+  /** Union of integer literals with default (closed enum) */
+  @default(1)
+  @closed
+  union Priority {
+    1,
+    2,
+    3,
+  }
+}

packages/emitter/test/spec/basic/output/com/example/scalarDefaults.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.scalarDefaults",
+  "defs": {
+    "main": {
+      "type": "object",
+      "properties": {
+        "mode": {
+          "type": "ref",
+          "ref": "#mode",
+          "description": "Uses string scalar with default"
+        },
+        "limit": {
+          "type": "ref",
+          "ref": "#limit",
+          "description": "Uses integer scalar with default"
+        },
+        "enabled": {
+          "type": "ref",
+          "ref": "#enabled",
+          "description": "Uses boolean scalar with default"
+        }
+      },
+      "description": "Test default decorator on scalars"
+    },
+    "mode": {
+      "type": "string",
+      "maxLength": 50,
+      "default": "standard",
+      "description": "A string type with a default value"
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 50,
+      "description": "An integer type with a default value"
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "A boolean type with a default value"
+    }
+  }
+}

packages/emitter/test/spec/basic/output/com/example/scalarDefs.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.scalarDefs",
+  "defs": {
+    "main": {
+      "type": "object",
+      "properties": {
+        "tag": {
+          "type": "ref",
+          "ref": "#tag",
+          "description": "Uses a custom string scalar with constraints"
+        },
+        "count": {
+          "type": "ref",
+          "ref": "#count",
+          "description": "Uses a custom integer scalar with constraints"
+        }
+      },
+      "description": "Scalar defs should create standalone defs like models and unions"
+    },
+    "tag": {
+      "type": "string",
+      "maxLength": 100,
+      "maxGraphemes": 50,
+      "description": "A custom string type with length constraints"
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "A custom integer type with value constraints"
+    }
+  }
+}

packages/emitter/test/spec/basic/output/com/example/scalarInline.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.scalarInline",
+  "defs": {
+    "main": {
+      "type": "object",
+      "properties": {
+        "tag": {
+          "type": "string",
+          "maxLength": 50,
+          "maxGraphemes": 25,
+          "description": "Inline scalar - should not create a def"
+        },
+        "category": {
+          "type": "ref",
+          "ref": "#category",
+          "description": "Non-inline scalar - should create a def"
+        }
+      },
+      "description": "Test inline decorator on scalars"
+    },
+    "category": {
+      "type": "string",
+      "maxLength": 100,
+      "description": "A regular scalar should create a standalone def"
+    }
+  }
+}

packages/emitter/test/spec/basic/output/com/example/unionDefaults.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.unionDefaults",
+  "defs": {
+    "main": {
+      "type": "object",
+      "properties": {
+        "eventMode": {
+          "type": "ref",
+          "ref": "#eventMode",
+          "description": "Union with token refs and default"
+        },
+        "sortOrder": {
+          "type": "ref",
+          "ref": "#sortOrder",
+          "description": "Union with string literals and default"
+        },
+        "priority": {
+          "type": "ref",
+          "ref": "#priority",
+          "description": "Union with integer literals and default"
+        }
+      },
+      "description": "Test default decorator on unions"
+    },
+    "eventMode": {
+      "type": "string",
+      "knownValues": [
+        "com.example.unionDefaults#hybrid",
+        "com.example.unionDefaults#inperson",
+        "com.example.unionDefaults#virtual"
+      ],
+      "default": "com.example.unionDefaults#inperson",
+      "description": "Union of tokens with default pointing to a token"
+    },
+    "hybrid": {
+      "type": "token",
+      "description": "A hybrid event"
+    },
+    "inperson": {
+      "type": "token",
+      "description": "An in-person event"
+    },
+    "virtual": {
+      "type": "token",
+      "description": "A virtual event"
+    },
+    "sortOrder": {
+      "type": "string",
+      "knownValues": ["asc", "desc"],
+      "default": "asc",
+      "description": "Union of string literals with default"
+    },
+    "priority": {
+      "type": "integer",
+      "enum": [1, 2, 3],
+      "default": 1,
+      "description": "Union of integer literals with default (closed enum)"
+    }
+  }
+}