diff --git a/crates/plotnik-lib/src/diagnostics/message.rs b/crates/plotnik-lib/src/diagnostics/message.rs
index 2b95bd88..b30d1646 100644
--- a/crates/plotnik-lib/src/diagnostics/message.rs
+++ b/crates/plotnik-lib/src/diagnostics/message.rs
@@ -1,8 +1,5 @@
-//! Diagnostic message types and related structures.
-
 use rowan::TextRange;
 
-/// Severity level of a diagnostic.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum Severity {
     #[default]
@@ -19,7 +16,6 @@ impl std::fmt::Display for Severity {
     }
 }
 
-/// A suggested fix for a diagnostic.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Fix {
     pub(crate) replacement: String,
@@ -35,7 +31,6 @@ impl Fix {
     }
 }
 
-/// Related location information for a diagnostic.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RelatedInfo {
     pub(crate) range: TextRange,
@@ -51,7 +46,6 @@ impl RelatedInfo {
     }
 }
 
-/// A diagnostic message with location, message, severity, and optional fix.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct DiagnosticMessage {
     pub(crate) severity: Severity,
diff --git a/crates/plotnik-lib/src/diagnostics/mod.rs b/crates/plotnik-lib/src/diagnostics/mod.rs
index 496d051d..19b8bc64 100644
--- a/crates/plotnik-lib/src/diagnostics/mod.rs
+++ b/crates/plotnik-lib/src/diagnostics/mod.rs
@@ -1,7 +1,3 @@
-//! Compiler diagnostics infrastructure.
-//!
-//! This module provides types for collecting and rendering diagnostic messages.
-
 mod message;
 mod printer;
 
@@ -15,13 +11,11 @@ pub use printer::DiagnosticsPrinter;
 
 use message::{DiagnosticMessage, Fix, RelatedInfo};
 
-/// Collection of diagnostic messages from parsing and analysis.
 #[derive(Debug, Clone, Default)]
 pub struct Diagnostics {
     messages: Vec<DiagnosticMessage>,
 }
 
-/// Builder for constructing a diagnostic message.
 #[must_use = "diagnostic not emitted, call .emit()"]
 pub struct DiagnosticBuilder<'a> {
     diagnostics: &'a mut Diagnostics,
diff --git a/crates/plotnik-lib/src/parser/grammar.rs b/crates/plotnik-lib/src/parser/grammar.rs
index af198028..6915e6cd 100644
--- a/crates/plotnik-lib/src/parser/grammar.rs
+++ b/crates/plotnik-lib/src/parser/grammar.rs
@@ -18,7 +18,6 @@ impl Parser<'_> {
     pub fn parse_root(&mut self) {
         self.start_node(SyntaxKind::Root);
 
-        // Track spans of unnamed defs to emit errors for non-last ones
         let mut unnamed_def_spans: Vec<TextRange> = Vec::new();
 
         while !self.has_fatal_error() && (self.peek() != SyntaxKind::Error || !self.eof()) {
@@ -26,16 +25,13 @@ impl Parser<'_> {
             if self.peek() == SyntaxKind::Id && self.peek_nth(1) == SyntaxKind::Equals {
                 self.parse_def();
             } else {
-                // Anonymous def: wrap expression in Def node
                 let start = self.current_span().start();
                 self.start_node(SyntaxKind::Def);
                 let success = self.parse_expr_or_error();
                 if !success {
-                    // Synchronize: consume remaining garbage until next def boundary
                     self.synchronize_to_def_start();
                 }
                 self.finish_node();
-                // Only track successfully parsed defs for validation
                 if success {
                     let end = self.last_non_trivia_end().unwrap_or(start);
                     unnamed_def_spans.push(TextRange::new(start, end));
@@ -43,7 +39,6 @@ impl Parser<'_> {
             }
         }
 
-        // Emit errors for all unnamed defs except the last one
         if unnamed_def_spans.len() > 1 {
             for span in &unnamed_def_spans[..unnamed_def_spans.len() - 1] {
                 let def_text = &self.source[usize::from(span.start())..usize::from(span.end())];
@@ -164,12 +159,10 @@ impl Parser<'_> {
     /// PascalCase identifiers without children become `Ref` nodes.
     /// PascalCase identifiers with children emit an error but parse as `Tree`.
     fn parse_tree(&mut self) {
-        // Use checkpoint so we can decide Tree vs Ref after seeing the full content
         let checkpoint = self.checkpoint();
         self.push_delimiter(SyntaxKind::ParenOpen);
         self.bump(); // consume '('
 
-        // Track if this is a reference (PascalCase identifier)
         let mut is_ref = false;
         let mut ref_name: Option<String> = None;
 
@@ -199,7 +192,6 @@ impl Parser<'_> {
                 }
 
                 if self.peek() == SyntaxKind::Slash {
-                    // Supertype syntax - commit to Tree
                     if is_ref {
                         self.start_node_at(checkpoint, SyntaxKind::Tree);
                         self.error("references cannot use supertype syntax (/)");
diff --git a/crates/plotnik-lib/src/parser/lexer.rs b/crates/plotnik-lib/src/parser/lexer.rs
index a284665e..ff75ed0b 100644
--- a/crates/plotnik-lib/src/parser/lexer.rs
+++ b/crates/plotnik-lib/src/parser/lexer.rs
@@ -92,13 +92,11 @@ fn split_string_literal(source: &str, span: Range<usize>, tokens: &mut Vec<Token
     let start = span.start;
     let end = span.end;
 
-    // Opening quote
     tokens.push(Token::new(
         quote_kind,
         range_to_text_range(start..start + 1),
     ));
 
-    // Content (may be empty)
     if end - start > 2 {
         tokens.push(Token::new(
             SyntaxKind::StrVal,
@@ -106,7 +104,6 @@ fn split_string_literal(source: &str, span: Range<usize>, tokens: &mut Vec<Token
         ));
     }
 
-    // Closing quote
     tokens.push(Token::new(quote_kind, range_to_text_range(end - 1..end)));
 }
 
diff --git a/crates/plotnik-lib/src/query/printer.rs b/crates/plotnik-lib/src/query/printer.rs
index 2d88d90b..fbb8581c 100644
--- a/crates/plotnik-lib/src/query/printer.rs
+++ b/crates/plotnik-lib/src/query/printer.rs
@@ -80,7 +80,6 @@ impl<'q, 'src> QueryPrinter<'q, 'src> {
 
         let defined: IndexSet<&str> = symbols.names().collect();
 
-        // Build map from name to body syntax node for cardinality lookup
         let mut body_nodes: HashMap<String, SyntaxNode> = HashMap::new();
         for def in self.query.root().defs() {
             if let (Some(name_tok), Some(body)) = (def.name(), def.body()) {
@@ -88,7 +87,6 @@ impl<'q, 'src> QueryPrinter<'q, 'src> {
             }
         }
 
-        // Print all definitions in definition order
         for name in symbols.names() {
             let mut visited = IndexSet::new();
             self.format_symbol_tree(name, 0, &defined, &body_nodes, &mut visited, w)?;