diff --git a/src/ir/types.zig b/src/ir/types.zig
index 7526633..2a7944a 100644
--- a/src/ir/types.zig
+++ b/src/ir/types.zig
@@ -332,7 +332,7 @@ pub const TypeTable = struct {
     slice_arena: std.heap.ArenaAllocator,
     /// Target pointer size in bytes (4 for wasm32, 8 for 64-bit targets).
     pointer_size: u8 = 8,
-    /// Borrowed pointer to Lowering's `type_alias_map`. When set,
+    /// Borrowed pointer to `Lowering.program_index.type_alias_map`. When set,
     /// `resolveTypeName` consults it before falling through to
     /// the empty-struct-stub default — so a name like `ShaderHandle`
     /// (defined `ShaderHandle :: u32`) resolves to `u32` rather than
diff --git a/src/sema.zig b/src/sema.zig
index 97d2293..01391e2 100644
--- a/src/sema.zig
+++ b/src/sema.zig
@@ -1,3 +1,19 @@
+//! Editor-facing symbol/type INDEX for the language server — not a compiler
+//! semantic pass.
+//!
+//! Powers editor navigation and completion (go-to-definition, find-references,
+//! hover, member/field lookup) by building a best-effort, resilient view of a
+//! file's symbols and approximate types. The `Type` values here come from
+//! `src/types.zig`, which is editor metadata only.
+//!
+//! This is NOT the compiler's source of truth. Compiler type resolution,
+//! lowering, and codegen consume the canonical `TypeId` / `TypeTable` model in
+//! `src/ir/`, never this module. sx does not require as-you-type type checking;
+//! authoritative diagnostics are produced on save by running the canonical
+//! compiler pipeline (`src/lsp/server.zig`), not by this analyzer. The public
+//! names below (`Analyzer`, `analyze`, `inferExprType`, `resolveTypeNode`,
+//! `SemaResult`) name an editor index, not compiler authority.
+
 const std = @import("std");
 const ast = @import("ast.zig");
 const Node = ast.Node;
@@ -60,6 +76,9 @@ pub const StructTypeInfo = struct {
 
 pub const TypeMap = std.AutoHashMap(*const Node, Type);
 
+/// Editor index for one file: symbols, references, member refs, approximate
+/// types, and best-effort diagnostics for navigation/completion. Not consumed
+/// by the compiler pipeline (see module doc).
 pub const SemaResult = struct {
     symbols: []const Symbol,
     references: []const Reference,
@@ -72,6 +91,8 @@ pub const SemaResult = struct {
     type_map: TypeMap,
 };
 
+/// Builds the editor symbol/type index (see module doc). Not a compiler
+/// semantic pass — its `Type` results are editor metadata, not compiler truth.
 pub const Analyzer = struct {
     allocator: std.mem.Allocator,
     symbols: std.ArrayList(Symbol),
@@ -328,7 +349,8 @@ pub const Analyzer = struct {
         try self.fn_signatures.put(key, .{ .param_types = &.{}, .return_type = ret });
     }
 
-    /// Resolve a type annotation node to a Type.
+    /// Resolve a type annotation node to an editor `Type` (metadata only — the
+    /// compiler resolves type nodes to canonical `TypeId` in `src/ir/`).
     /// Handles primitives, type_expr, array_type_expr, parameterized_type_expr,
     /// type aliases, enum types, and struct types.
     pub fn resolveTypeNode(self: *Analyzer, type_node: ?*Node) Type {
@@ -540,7 +562,8 @@ pub const Analyzer = struct {
         return .{ .struct_type = mangled };
     }
 
-    /// Infer the type of an expression node without LLVM.
+    /// Infer an approximate editor `Type` for an expression (hover/completion;
+    /// metadata only — NOT a compiler type decision, which uses `TypeId`).
     /// Uses fn_signatures for call return types, struct_types for field access,
     /// symbols for identifier types, and Type.widen for arithmetic promotion.
     pub fn inferExprType(self: *Analyzer, node: *const Node) Type {
diff --git a/src/types.zig b/src/types.zig
index 08d661b..2a98a91 100644
--- a/src/types.zig
+++ b/src/types.zig
@@ -2,6 +2,12 @@ const std = @import("std");
 const ast = @import("ast.zig");
 const Node = ast.Node;
 
+/// Editor metadata type model, used only by `src/sema.zig` (the language-server
+/// symbol/type index) for navigation, completion, and hover. NOT the compiler's
+/// source of truth: lowering, codegen, and layout use the canonical
+/// `TypeId` / `TypeTable` model in `src/ir/types.zig`. Do not expand this to
+/// carry new compiler semantics; the architecture endpoint (phase A8) is to
+/// delete it or reduce it to display-only data derived from `TypeId`.
 pub const Type = union(enum) {
     // Variable-width integers (1–64 bits)
     signed: u8,