diff --git a/crates/wright-analyzer/src/analysis.rs b/crates/wright-analyzer/src/analysis.rs
index 3e62170d..3867d4a1 100644
--- a/crates/wright-analyzer/src/analysis.rs
+++ b/crates/wright-analyzer/src/analysis.rs
@@ -1,5 +1,3 @@
-//! Workshop-specific static analyses over Workshop IR and CFG.
-//!
 //! Each analysis produces [`Finding`]s with a stable code, a severity, a
 //! human-readable message, and the offending rule/action/value and span. The
 //! v0.2 analysis set is deliberately small and low-false-positive:
diff --git a/crates/wright-analyzer/src/cfg.rs b/crates/wright-analyzer/src/cfg.rs
index 332fa6fd..0b911a4c 100644
--- a/crates/wright-analyzer/src/cfg.rs
+++ b/crates/wright-analyzer/src/cfg.rs
@@ -1,5 +1,3 @@
-//! Control-flow graphs over Workshop IR rules.
-//!
 //! [`Cfg`] flattens a rule's structured actions (If/While/ForGlobalVariable)
 //! into basic blocks while preserving the structured semantics: branch edges,
 //! loop back-edges, and loop exits are explicit [`EdgeKind`]s, so timing and
diff --git a/crates/wright-analyzer/src/lib.rs b/crates/wright-analyzer/src/lib.rs
index 1cc663aa..716e4286 100644
--- a/crates/wright-analyzer/src/lib.rs
+++ b/crates/wright-analyzer/src/lib.rs
@@ -1,17 +1,3 @@
-//! Wright's semantic analysis and agent tooling layer.
-//!
-//! This crate builds on [`wright_ir`] to expose read-only semantic services
-//! over compiled programs (ADR-0006):
-//!
-//! * [`symbols`] — symbol tables, reference indices, and usage queries;
-//! * [`cfg`] — control-flow graphs and timing-aware primitives;
-//! * `analysis` — Workshop-specific static analyses producing findings;
-//! * `service` — the transport-neutral read-only tool/agent interface.
-//!
-//! The crate is protocol-agnostic: it operates on [`wir::Program`], and the
-//! `wright-tool` binary wires the pipeline in `wright-core` (protocol →
-//! internal HIR → Workshop IR) into these services.
-
 pub mod analysis;
 pub mod cfg;
 pub mod registry;
diff --git a/crates/wright-analyzer/src/registry.rs b/crates/wright-analyzer/src/registry.rs
index 0d5afbec..41dc3b03 100644
--- a/crates/wright-analyzer/src/registry.rs
+++ b/crates/wright-analyzer/src/registry.rs
@@ -1,9 +1,3 @@
-//! Lint rule registry and configuration contract (#97).
-//!
-//! This module defines the stable rule-identity and metadata types, the
-//! [`LintRegistry`] that holds the first-party rule set, and [`LintConfig`]
-//! that controls which rules are active and at what severity.
-//!
 //! # Contract
 //!
 //! * Rule IDs are stable `&'static str` values that match the `code` field on
@@ -28,8 +22,6 @@ use crate::analysis::{
 };
 use crate::cfg::Cfg;
 
-// ── Rule metadata ─────────────────────────────────────────────────────────────
-
 /// Static metadata for one lint rule.
 ///
 /// All fields are `&'static str` / `&'static [&'static str]` to support
@@ -58,8 +50,6 @@ pub struct RuleMeta {
     pub tags: &'static [&'static str],
 }
 
-// ── Per-rule configuration ────────────────────────────────────────────────────
-
 /// Configuration applied to one rule at registry execution time.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RuleConfig {
@@ -113,8 +103,6 @@ impl From<Severity> for SeverityLabel {
     }
 }
 
-// ── Lint configuration ────────────────────────────────────────────────────────
-
 /// The deterministic lint configuration passed to [`LintRegistry::run`].
 ///
 /// [`LintConfig::default`] enables all registered rules at their default
@@ -186,8 +174,6 @@ impl LintConfig {
     }
 }
 
-// ── Registry ──────────────────────────────────────────────────────────────────
-
 /// One registered rule: its stable metadata and the analysis implementation.
 struct RegistryEntry {
     meta: RuleMeta,
diff --git a/crates/wright-analyzer/src/service.rs b/crates/wright-analyzer/src/service.rs
index 83466788..0c94a150 100644
--- a/crates/wright-analyzer/src/service.rs
+++ b/crates/wright-analyzer/src/service.rs
@@ -1,14 +1,9 @@
-//! The read-only agent/tool interface over Wright's semantic services.
-//!
 //! [`SemanticService`] answers transport-neutral JSON requests about a
 //! compiled Workshop IR program: program summary, rule/action/value lookup,
 //! symbol/reference inspection, usage, CFG inspection, and static-analysis
 //! findings. The request/response models ([`Request`], [`Response`]) are
 //! plain serde data with no transport or UI dependency, and there is no
 //! mutation or AST-editing contract in v0.2.
-//!
-//! The `wright-tool` binary wires the pipeline (protocol JSON → internal HIR
-//! → Workshop IR) into this service and serves requests over stdin/stdout.
 
 use serde::{Deserialize, Serialize};
 use serde_json::json;
diff --git a/crates/wright-analyzer/src/symbols.rs b/crates/wright-analyzer/src/symbols.rs
index a2acf9a7..fa409cf8 100644
--- a/crates/wright-analyzer/src/symbols.rs
+++ b/crates/wright-analyzer/src/symbols.rs
@@ -1,5 +1,3 @@
-//! Symbol tables, reference indices, and usage queries over Workshop IR.
-//!
 //! [`SemanticIndex`] is the read-only semantic query surface for tooling and
 //! agents: it enumerates every symbol (global/player variables, subroutines,
 //! rules), records every reference site (declarations, reads, writes, calls,
@@ -251,7 +249,6 @@ impl<'a> Builder<'a> {
             )?;
         }
 
-        // References from rule bodies.
         for id in 0..self.program.rules.len() {
             self.walk_rule(RuleId::from_index(id))?;
         }
diff --git a/crates/wright-bench/src/main.rs b/crates/wright-bench/src/main.rs
index 64cfc16e..86c94a4e 100644
--- a/crates/wright-bench/src/main.rs
+++ b/crates/wright-bench/src/main.rs
@@ -1,5 +1,3 @@
-//! `wright-bench` — reproducible performance and resource benchmarks (#53).
-//!
 //! Measures compile latency, peak RSS, and generated-resource usage (emitted
 //! Workshop bytes, WIR node counts) for the versioned corpus through the
 //! real driver path (`CompilerSession::compile`), and enforces declared
diff --git a/crates/wright-cli/src/bin/wright-serve.rs b/crates/wright-cli/src/bin/wright-serve.rs
index 1bb4b0d1..16811ddc 100644
--- a/crates/wright-cli/src/bin/wright-serve.rs
+++ b/crates/wright-cli/src/bin/wright-serve.rs
@@ -1,6 +1,3 @@
-//! `wright-serve` — thin transport adapters over the session-aware tool
-//! service (issue #60).
-//!
 //! Exposes the same operations as [`wright_driver::service::ToolService`]
 //! over two transports:
 //!
@@ -10,9 +7,8 @@
 //! * **JSON-RPC 2.0** (`--transport jsonrpc`): standard JSON-RPC envelopes
 //!   with `id`/`method`/`params` and `result`/`error` responses.
 //!
-//! Both are thin mappings: no semantic logic lives here, so behavior is
-//! identical to in-process consumers. MCP is intentionally not implemented —
-//! no agent-integration evidence justified it in v1.
+//! MCP is intentionally not implemented — no agent-integration evidence
+//! justified it in v1.
 
 use std::io::{BufRead, Write};
 use std::process::ExitCode;
diff --git a/crates/wright-cli/src/cli.rs b/crates/wright-cli/src/cli.rs
index 562c02f9..464a2ae8 100644
--- a/crates/wright-cli/src/cli.rs
+++ b/crates/wright-cli/src/cli.rs
@@ -1,5 +1,3 @@
-//! The authoritative structured command model for `wright`.
-
 use std::path::PathBuf;
 
 use clap::{Args, Parser, Subcommand, ValueEnum};
diff --git a/crates/wright-cli/src/completion.rs b/crates/wright-cli/src/completion.rs
index 9bcff798..dc87d997 100644
--- a/crates/wright-cli/src/completion.rs
+++ b/crates/wright-cli/src/completion.rs
@@ -1,5 +1,3 @@
-//! Shell completion generation, detection, installation, and refresh (#186).
-//!
 //! Provides the authoritative lifecycle for shell completions generated from
 //! the `clap` command model. Supports pure generation (`wright completion <shell>`),
 //! automatic or explicit installation into conventional user-local locations
diff --git a/crates/wright-cli/src/main.rs b/crates/wright-cli/src/main.rs
index 61ca90c1..aa4121bf 100644
--- a/crates/wright-cli/src/main.rs
+++ b/crates/wright-cli/src/main.rs
@@ -1,5 +1,3 @@
-//! `wright` — the primary Wright command-line interface.
-
 mod cli;
 mod completion;
 mod present;
diff --git a/crates/wright-cli/src/provider.rs b/crates/wright-cli/src/provider.rs
index a85b1465..2412a1c0 100644
--- a/crates/wright-cli/src/provider.rs
+++ b/crates/wright-cli/src/provider.rs
@@ -1,5 +1,3 @@
-//! First-party language-provider management commands.
-
 use wright_driver::{OpyProviderConfig, OpyProviderError, ResolvedOpyProvider};
 
 /// Explicitly install/update the first-party OPY provider.
diff --git a/crates/wright-cli/src/update.rs b/crates/wright-cli/src/update.rs
index d2019b3d..ed00b631 100644
--- a/crates/wright-cli/src/update.rs
+++ b/crates/wright-cli/src/update.rs
@@ -1,5 +1,3 @@
-//! `wright update` — self-update for standalone installations (#116).
-//!
 //! Resolves the latest stable Wright release from the canonical GitHub
 //! Release contract (the same archives and checksums `install.sh` and the
 //! package-manager manifests consume), verifies the published SHA-256
diff --git a/crates/wright-consumer/src/lib.rs b/crates/wright-consumer/src/lib.rs
index 22338d5f..ec735e8b 100644
--- a/crates/wright-consumer/src/lib.rs
+++ b/crates/wright-consumer/src/lib.rs
@@ -1,5 +1,3 @@
-//! The external consumer's public API surface (issue #61).
-//!
 //! [`run_consumer`] drives every public embedding/tool workflow over one
 //! input, proving that a consumer depending only on `wright-driver` can
 //! compile/check/analyze/query and validate edits without internal IR
diff --git a/crates/wright-consumer/src/main.rs b/crates/wright-consumer/src/main.rs
index 9aa208ce..2f7fb68c 100644
--- a/crates/wright-consumer/src/main.rs
+++ b/crates/wright-consumer/src/main.rs
@@ -1,5 +1,3 @@
-//! The external consumer binary (issue #61).
-
 fn main() {
     let input = std::env::args().nth(1).unwrap_or_else(|| {
         eprintln!("usage: wright-consumer <input>");
diff --git a/crates/wright-consumer/src/workflow.rs b/crates/wright-consumer/src/workflow.rs
index 37072d82..5ba95052 100644
--- a/crates/wright-consumer/src/workflow.rs
+++ b/crates/wright-consumer/src/workflow.rs
@@ -12,11 +12,9 @@ pub fn run_consumer(input: &str) -> Result<(), String> {
     };
     let mut session = CompilerSession::new(config).map_err(|error| error.message)?;
 
-    // Check through the shared session.
     let check = session.check();
     assert!(check.ok, "check passes: {:?}", check.diagnostics);
 
-    // Compile through the shared session.
     let compile = session.compile();
     assert!(compile.ok, "compile passes: {:?}", compile.diagnostics);
     let output = compile.result.output.expect("compiled output");
@@ -27,7 +25,6 @@ pub fn run_consumer(input: &str) -> Result<(), String> {
         &output.sha256[..16]
     );
 
-    // Analyze through the shared session.
     let analyze = session.analyze();
     assert!(analyze.ok, "analyze passes");
     println!(
@@ -36,8 +33,6 @@ pub fn run_consumer(input: &str) -> Result<(), String> {
         analyze.result.facts["rules"].as_array().unwrap().len()
     );
 
-    // Lint through the shared session (#98): the same pipeline with
-    // rule metadata, effective configuration, and evidence-tagged findings.
     let lint = session.lint();
     assert!(lint.ok, "lint passes: {:?}", lint.diagnostics);
     println!(
@@ -46,7 +41,6 @@ pub fn run_consumer(input: &str) -> Result<(), String> {
         lint.result.rules.as_array().unwrap().len()
     );
 
-    // Session-aware tool service queries (structured owned results).
     let service = ToolService::new(&mut session).map_err(|error| error.message)?;
     let capabilities = service.handle(&ToolRequest::Capabilities);
     match capabilities {
@@ -76,8 +70,6 @@ pub fn run_consumer(input: &str) -> Result<(), String> {
         let response = service.handle(&request);
         match response {
             wright_driver::service::ToolResponse::Ok { result } => {
-                // The tool lint path carries the same evidence-tagged
-                // findings as the session/CLI path.
                 if matches!(request, ToolRequest::Lint) {
                     let findings = result["findings"].as_array().unwrap();
                     for finding in findings {
@@ -94,8 +86,6 @@ pub fn run_consumer(input: &str) -> Result<(), String> {
         }
     }
 
-    // Safe rename: propose, validate through the project transaction
-    // contract, preview (#128: the shared frontend-neutral contract).
     if input.ends_with(".opy") {
         if let Some(name) = first_global(&source) {
             let identity = wright_driver::input_identity(&source);
diff --git a/crates/wright-core/src/hir/convert.rs b/crates/wright-core/src/hir/convert.rs
index 8b8a3452..e3074152 100644
--- a/crates/wright-core/src/hir/convert.rs
+++ b/crates/wright-core/src/hir/convert.rs
@@ -1,6 +1,3 @@
-//! Conversion from the `wright/opy-hir` bridge protocol into the internal
-//! Opy HIR model (`wright_ir::hir`).
-//!
 //! The protocol payload is expected to be already validated (see
 //! [`super::parse_str`]); this conversion maps it onto the typed, arena-based
 //! model, resolving name references to typed IDs and rejecting operators
@@ -55,14 +52,11 @@ impl<'a> Builder<'a> {
     }
 
     fn build(mut self) -> Result<wright_ir::hir::Program, IrError> {
-        // Phase A: file registry.
         for file in &self.protocol.files {
             let id = self.target.files.push(SourceFile::new(file.path.clone()));
             self.files.insert(file.id, id);
         }
 
-        // Phase A: symbols with empty bodies; maps are populated before any
-        // body conversion so references resolve regardless of order.
         for declaration in &self.protocol.declarations {
             match declaration {
                 Declaration::GlobalVariable {
@@ -143,7 +137,6 @@ impl<'a> Builder<'a> {
             }
         }
 
-        // Phase B: merge subroutine definitions into the subroutine table.
         for entry in &self.protocol.rules {
             if let RuleEntry::SubroutineDef {
                 name,
@@ -183,7 +176,6 @@ impl<'a> Builder<'a> {
             }
         }
 
-        // Phase C: initializers, constant values, and macro bodies.
         for declaration in &self.protocol.declarations {
             match declaration {
                 Declaration::GlobalVariable {
@@ -230,7 +222,6 @@ impl<'a> Builder<'a> {
             }
         }
 
-        // Phase D: rules.
         for entry in &self.protocol.rules {
             if let RuleEntry::Rule(rule) = entry {
                 let event = wright_ir::hir::Event {
@@ -263,7 +254,6 @@ impl<'a> Builder<'a> {
             }
         }
 
-        // Phase E: the settings carrier (spans map through the registry).
         if let Some(settings) = &self.protocol.settings {
             let mut converted = Vec::with_capacity(settings.children.len());
             for child in &settings.children {
diff --git a/crates/wright-core/src/hir/dump.rs b/crates/wright-core/src/hir/dump.rs
index 4e074d24..4655702a 100644
--- a/crates/wright-core/src/hir/dump.rs
+++ b/crates/wright-core/src/hir/dump.rs
@@ -1,5 +1,3 @@
-//! Deterministic debug/pretty dump for Opy HIR v1 programs.
-//!
 //! The dump is a stable, human-readable rendering intended for tests and
 //! issue reports. It is not part of the wire contract: the same validated
 //! payload always produces the same dump, in payload order.
diff --git a/crates/wright-core/src/hir/error.rs b/crates/wright-core/src/hir/error.rs
index 54e69bcc..b28656fe 100644
--- a/crates/wright-core/src/hir/error.rs
+++ b/crates/wright-core/src/hir/error.rs
@@ -1,5 +1,3 @@
-//! Structured errors for Opy HIR v1 ingestion.
-//!
 //! Every failure carries a stable code, a message, and — when the offending
 //! source position is known — a span. Human-readable wording is not part of
 //! the stable contract; `code` is.
diff --git a/crates/wright-core/src/hir/mod.rs b/crates/wright-core/src/hir/mod.rs
index 269ad748..eb25d13c 100644
--- a/crates/wright-core/src/hir/mod.rs
+++ b/crates/wright-core/src/hir/mod.rs
@@ -1,5 +1,3 @@
-//! Opy HIR v1 — the Wright-owned frontend protocol consumed by the core.
-//!
 //! The wire contract is specified in
 //! [`docs/hir/opy-hir-v1.md`](../../../../docs/hir/opy-hir-v1.md). This module
 //! provides serde protocol types, envelope and structural validation, and a
diff --git a/crates/wright-core/src/hir/types.rs b/crates/wright-core/src/hir/types.rs
index e9d07ec1..64ed676f 100644
--- a/crates/wright-core/src/hir/types.rs
+++ b/crates/wright-core/src/hir/types.rs
@@ -1,5 +1,3 @@
-//! Serde protocol types for `wright/opy-hir` version `1.0.0`.
-//!
 //! These types mirror [`docs/hir/opy-hir-v1.md`](../../../../docs/hir/opy-hir-v1.md).
 //! Unknown fields on known nodes are tolerated so an additive producer change
 //! inside the same major version does not break the consumer; unknown node
diff --git a/crates/wright-core/src/hir/validate.rs b/crates/wright-core/src/hir/validate.rs
index de99c516..562ecb1b 100644
--- a/crates/wright-core/src/hir/validate.rs
+++ b/crates/wright-core/src/hir/validate.rs
@@ -1,5 +1,3 @@
-//! Opy HIR v1 validation.
-//!
 //! Validation follows the order in `docs/hir/opy-hir-v1.md` §8: the protocol
 //! envelope is checked first (in [`super::parse_value`]), then unknown node
 //! kinds are rejected with the offending kind name and span, then the payload
diff --git a/crates/wright-core/src/signatures.rs b/crates/wright-core/src/signatures.rs
index 54593bcf..f3437175 100644
--- a/crates/wright-core/src/signatures.rs
+++ b/crates/wright-core/src/signatures.rs
@@ -1,10 +1 @@
-//! Canonical signature context for ambiguous enum member resolution.
-//!
-//! Cutover shim (wright#143): the parse-context contract is owned by
-//! `workshop-rs` (`workshop_rs::signatures`); this module re-exports it so
-//! Wright's manifest owner (`wright-opy`) and the Workshop parse path keep
-//! implementing/consuming one trait. No independent implementation lives
-//! here. Removal path: when the OPY provider extracts to `opy-rs`, this shim
-//! disappears and importers use `workshop_rs::signatures` directly.
-
 pub use workshop_rs::signatures::*;
diff --git a/crates/wright-driver/src/config.rs b/crates/wright-driver/src/config.rs
index 4abc9022..086b131b 100644
--- a/crates/wright-driver/src/config.rs
+++ b/crates/wright-driver/src/config.rs
@@ -1,12 +1,3 @@
-//! Session configuration owned by the compiler driver.
-//!
-//! [`SessionConfig`] describes one driver run: where the input comes from,
-//! which frontend handles it, optional frontend overrides (Workshop locale,
-//! `.opy` include root), where compiled output goes, which presentation
-//! format the result is intended for, and the lint rule configuration. The
-//! CLI, library consumers, and later tool/LSP adapters all construct the
-//! same configuration type.
-
 use std::path::PathBuf;
 
 pub use wright_analyzer::registry::LintConfig;
diff --git a/crates/wright-driver/src/diag.rs b/crates/wright-driver/src/diag.rs
index 5d256004..95a8527b 100644
--- a/crates/wright-driver/src/diag.rs
+++ b/crates/wright-driver/src/diag.rs
@@ -1,5 +1,3 @@
-//! Structured diagnostics shared by every driver workflow.
-//!
 //! A [`Diagnostic`] is the machine-readable unit of compiler feedback: a
 //! stable `code`, the pipeline `stage` that produced it, a `severity`, a
 //! human message, an optional source span, and the input's origin metadata.
diff --git a/crates/wright-driver/src/edit.rs b/crates/wright-driver/src/edit.rs
index f9286ae0..91daf454 100644
--- a/crates/wright-driver/src/edit.rs
+++ b/crates/wright-driver/src/edit.rs
@@ -1,5 +1,3 @@
-//! Frontend-neutral source-edit transactions (#59, reconciled by #128).
-//!
 //! Tools and agents propose edits as validated, source-oriented
 //! [`SourceEdit`]s — never as mutations of Wright's internal IR. One
 //! [`EditTransaction`] carries one or more file edits with exact source
diff --git a/crates/wright-driver/src/input.rs b/crates/wright-driver/src/input.rs
index 7c1003ed..d8142296 100644
--- a/crates/wright-driver/src/input.rs
+++ b/crates/wright-driver/src/input.rs
@@ -1,5 +1,3 @@
-//! Source/project discovery: input kinds, path normalization, and stdin.
-//!
 //! The driver resolves one [`SessionConfig`] into a concrete
 //! [`ResolvedInput`]: the input text, the concrete frontend kind, a stable
 //! display identity for diagnostics, an include root for `.opy`, and a
diff --git a/crates/wright-driver/src/lib.rs b/crates/wright-driver/src/lib.rs
index 44a07386..dc0d0580 100644
--- a/crates/wright-driver/src/lib.rs
+++ b/crates/wright-driver/src/lib.rs
@@ -1,12 +1,3 @@
-//! Wright's reusable compiler/session driver.
-//!
-//! One orchestration path for every frontend and workflow: input discovery →
-//! frontend selection (`opy` bridge, native Workshop, or protocol JSON) →
-//! validation → lowering → analysis → emission. The `wright` CLI is a thin
-//! presentation layer over this crate, and later tool/LSP adapters reuse the
-//! same [`CompilerSession`]. Every workflow returns a typed [`Envelope`] whose
-//! JSON serialization is the machine-readable CLI contract.
-
 // Diagnostics are the primary error type of this crate, so error-returning
 // functions legitimately carry the full `Diagnostic` value; boxing it would
 // add an allocation per error without a measured benefit.
diff --git a/crates/wright-driver/src/opy.rs b/crates/wright-driver/src/opy.rs
index dc19ded3..8cd7a0f8 100644
--- a/crates/wright-driver/src/opy.rs
+++ b/crates/wright-driver/src/opy.rs
@@ -1,5 +1,3 @@
-//! The `.opy` frontend integration for the driver.
-//!
 //! The default `.opy` path is the native Rust frontend
 //! (`wright_opy`): no Node, no OverPy, stdin supported. The pinned OverPy
 //! adapter bridge remains available as an explicit compatibility fallback
diff --git a/crates/wright-driver/src/opy_provider.rs b/crates/wright-driver/src/opy_provider.rs
index a6acc966..1ee74eaa 100644
--- a/crates/wright-driver/src/opy_provider.rs
+++ b/crates/wright-driver/src/opy_provider.rs
@@ -1,9 +1,3 @@
-//! Resolution and installation of the first-party OPY LPP provider (#244).
-//!
-//! This module owns only distribution state. The provider process and wire
-//! protocol remain owned by `wright-lpp`, and OPY project loading remains an
-//! `opy-rs` concern.
-
 use std::fmt;
 use std::io::{Read, Write};
 use std::path::Path;
diff --git a/crates/wright-driver/src/progress.rs b/crates/wright-driver/src/progress.rs
index 41566dad..058d8c0d 100644
--- a/crates/wright-driver/src/progress.rs
+++ b/crates/wright-driver/src/progress.rs
@@ -1,5 +1,3 @@
-//! Transport-neutral workflow progress events.
-//!
 //! The driver reports semantic workflow boundaries without terminal strings,
 //! ANSI, timing, or presentation policy. CLI and embedding consumers may
 //! observe these events independently.
diff --git a/crates/wright-driver/src/provider_edit.rs b/crates/wright-driver/src/provider_edit.rs
index b0798e5d..56d1e05e 100644
--- a/crates/wright-driver/src/provider_edit.rs
+++ b/crates/wright-driver/src/provider_edit.rs
@@ -1,24 +1,3 @@
-//! Provider-driven source mutation (#139): language-specific semantic
-//! decisions route through LPP capabilities while Wright keeps the generic
-//! source-edit transaction guarantees.
-//!
-//! # The seam
-//!
-//! ```text
-//! ToolService / agent-facing mutation requests
-//!         |
-//!         |  ProviderRenameRequest / ProviderValidateRequest (source-oriented,
-//!         |  transport-neutral: documents + positions + current source texts)
-//!         v
-//!  provider_edit::semantic_rename / provider_edit::validate_transaction
-//!         |
-//!         |  lpp/rename            -- target resolution + edit generation
-//!         |  lpp/validateEdits     -- per-document edit application + re-parse
-//!         |  lpp/check             -- provider-owned project semantics
-//!         v
-//!  LanguageProvider (wright-lpp)   -- capability guards, typed LPP mapping
-//! ```
-//!
 //! Wright owns everything below, exactly as the shared `edit` machinery
 //! (`crate::edit`) defines it, and the guarantees are unchanged: edits carry
 //! source identity/version preconditions, the transaction orders edits
@@ -412,7 +391,6 @@ fn provider_validation(
     previews: &[SourcePreview],
     project_root: Option<&str>,
 ) -> Result<(), Refusal> {
-    // Gate 1: per-document edit validation.
     let mut grouped: BTreeMap<&str, Vec<&SourceEdit>> = BTreeMap::new();
     for edit in &transaction.edits {
         grouped.entry(edit.source.as_str()).or_default().push(edit);
@@ -479,7 +457,6 @@ fn provider_validation(
         }
     }
 
-    // Gate 2: provider-owned project semantics over the edited project.
     let mut edited = wright_lpp::DocumentSet::new();
     for (uri, document) in documents {
         let edited_text = previews
diff --git a/crates/wright-driver/src/result.rs b/crates/wright-driver/src/result.rs
index 65ad152b..62e55b21 100644
--- a/crates/wright-driver/src/result.rs
+++ b/crates/wright-driver/src/result.rs
@@ -1,5 +1,3 @@
-//! Typed result envelopes for every driver workflow.
-//!
 //! Each workflow returns a command-specific [`Envelope`] carrying the same
 //! deterministic shape: version/capability metadata, the command name, a
 //! boolean `ok`, the process exit code the CLI must use, the diagnostics, and
diff --git a/crates/wright-driver/src/service.rs b/crates/wright-driver/src/service.rs
index f2938a9d..aa8f8aa0 100644
--- a/crates/wright-driver/src/service.rs
+++ b/crates/wright-driver/src/service.rs
@@ -1,5 +1,3 @@
-//! The session-aware tool service (issues #57/#58).
-//!
 //! [`ToolService`] exposes Wright's compile/check/analyze/query workflows and
 //! agent-oriented semantic queries over stable public contracts, reusing the
 //! driver session. It is transport-neutral: the stdio/JSON-RPC adapters
diff --git a/crates/wright-driver/src/session.rs b/crates/wright-driver/src/session.rs
index 0e4149a0..93b1e517 100644
--- a/crates/wright-driver/src/session.rs
+++ b/crates/wright-driver/src/session.rs
@@ -1,9 +1,4 @@
-//! The reusable compiler/session driver (issue #37).
-//!
-//! [`CompilerSession`] is the single orchestration path shared by the CLI,
-//! library consumers, and (in later milestones) tool APIs and LSP: input
-//! resolution → frontend selection → validation → lowering → analysis →
-//! emission. Frontends are selected by [`SourceKind`] behind one contract, so
+//! Frontends are selected by [`SourceKind`] behind one contract, so
 //! the native `.opy` frontend can replace the temporary adapter bridge
 //! without changing callers. Every workflow returns a typed [`Envelope`]
 //! whose JSON serialization is the machine-readable CLI contract.
diff --git a/crates/wright-driver/src/source_provider.rs b/crates/wright-driver/src/source_provider.rs
index 61212187..03a24972 100644
--- a/crates/wright-driver/src/source_provider.rs
+++ b/crates/wright-driver/src/source_provider.rs
@@ -1,5 +1,3 @@
-//! Wright's product-facing source-provider boundary.
-//!
 //! The product layer selects a source target and receives source diagnostics
 //! plus canonical Workshop text. Provider transport, document synchronization,
 //! and compiler implementation types stay behind the adapter that implements
diff --git a/crates/wright-driver/src/workshop_compat.rs b/crates/wright-driver/src/workshop_compat.rs
index 28aa1fb1..a007f905 100644
--- a/crates/wright-driver/src/workshop_compat.rs
+++ b/crates/wright-driver/src/workshop_compat.rs
@@ -1,5 +1,3 @@
-//! Semantic comparison used by the OPY integration gate.
-//!
 //! Workshop meaning remains owned by `workshop-rs`; this module only adapts
 //! its parser and equivalence contract to the gate's two text inputs and
 //! preserves the comparison evidence for CI reports.
diff --git a/crates/wright-driver/src/workshop_provider.rs b/crates/wright-driver/src/workshop_provider.rs
index 745ff0a5..55e91c8e 100644
--- a/crates/wright-driver/src/workshop_provider.rs
+++ b/crates/wright-driver/src/workshop_provider.rs
@@ -1,5 +1,3 @@
-//! In-process raw Workshop provider.
-
 use std::path::{Path, PathBuf};
 
 use wright_core::provider::{
diff --git a/crates/wright-ir/src/arena.rs b/crates/wright-ir/src/arena.rs
index b158a3d6..01b767c9 100644
--- a/crates/wright-ir/src/arena.rs
+++ b/crates/wright-ir/src/arena.rs
@@ -1,9 +1 @@
-//! Bounds-checked arena storage for nodes.
-//!
-//! Cutover shim (wright#143): the generic IR infrastructure is owned by
-//! `workshop-rs`; this module re-exports it so the Opy HIR and the Workshop IR
-//! share one arena/ID identity. No independent implementation lives here.
-//! Removal path: when the HIR and lowering extract to `opy-rs`, this shim
-//! disappears and the HIR imports `workshop_rs::arena` directly.
-
 pub use workshop_rs::arena::*;
diff --git a/crates/wright-ir/src/error.rs b/crates/wright-ir/src/error.rs
index 72620663..f0adf0bf 100644
--- a/crates/wright-ir/src/error.rs
+++ b/crates/wright-ir/src/error.rs
@@ -1,12 +1,3 @@
-//! Structured IR errors.
-//!
-//! [`IrError`] is the Workshop IR error contract, owned by `workshop-rs`
-//! (`workshop_rs::wir::error::IrError`) and re-exported here so the Opy
-//! conversion, validation, and lowering paths keep one error type (cutover
-//! shim, wright#143). No independent implementation lives here. Removal
-//! path: when the HIR and lowering extract to `opy-rs`, this shim disappears
-//! and importers use `workshop_rs::wir::error` directly.
-
 use workshop_rs::source::Span;
 
 pub use workshop_rs::wir::error::IrError;
diff --git a/crates/wright-ir/src/format.rs b/crates/wright-ir/src/format.rs
index be5ea5ca..200e249e 100644
--- a/crates/wright-ir/src/format.rs
+++ b/crates/wright-ir/src/format.rs
@@ -1,9 +1 @@
-//! Formatting helpers shared by the IR layers.
-//!
-//! Cutover shim (wright#143): owned by `workshop-rs`; re-exported so the Opy
-//! frontend and the Workshop IR share one implementation. No independent
-//! implementation lives here. Removal path: when the HIR and lowering extract
-//! to `opy-rs`, this shim disappears and importers use
-//! `workshop_rs::format` directly.
-
 pub use workshop_rs::format::*;
diff --git a/crates/wright-ir/src/hir/dump.rs b/crates/wright-ir/src/hir/dump.rs
index 5ed159b4..aec875a3 100644
--- a/crates/wright-ir/src/hir/dump.rs
+++ b/crates/wright-ir/src/hir/dump.rs
@@ -1,5 +1,3 @@
-//! Deterministic debug dump for the internal Opy HIR model.
-
 use workshop_rs::source::Span;
 
 use super::{Event, Expr, Program, Stmt, UnaryOp};
diff --git a/crates/wright-ir/src/hir/validate.rs b/crates/wright-ir/src/hir/validate.rs
index 46e6db2f..ed556baf 100644
--- a/crates/wright-ir/src/hir/validate.rs
+++ b/crates/wright-ir/src/hir/validate.rs
@@ -1,5 +1,3 @@
-//! Structural validation of the internal Opy HIR model.
-
 use crate::error::IrError;
 use workshop_rs::source::Span;
 
diff --git a/crates/wright-ir/src/ids.rs b/crates/wright-ir/src/ids.rs
index 4197ca40..0561695a 100644
--- a/crates/wright-ir/src/ids.rs
+++ b/crates/wright-ir/src/ids.rs
@@ -1,10 +1 @@
-//! Strongly typed IDs.
-//!
-//! Cutover shim (wright#143): the generic IR infrastructure is owned by
-//! `workshop-rs`; this module re-exports it so the Opy HIR, the HIR → WIR
-//! lowering, and the Workshop IR share one type identity. No independent
-//! implementation lives here. Removal path: when the HIR and lowering extract
-//! to `opy-rs`, this shim disappears and the HIR imports
-//! `workshop_rs::ids` directly.
-
 pub use workshop_rs::ids::*;
diff --git a/crates/wright-ir/src/lib.rs b/crates/wright-ir/src/lib.rs
index 1f526c3c..51bd758b 100644
--- a/crates/wright-ir/src/lib.rs
+++ b/crates/wright-ir/src/lib.rs
@@ -1,24 +1,3 @@
-//! Wright's typed intermediate-representation core.
-//!
-//! This crate owns the Opy-frontend IR content described by
-//! [`docs/adr/0006-rust-ir-core.md`](../../docs/adr/0006-rust-ir-core.md):
-//!
-//! * [`hir`] — the internal Opy HIR model (frontend semantics);
-//! * [`lower`] — the HIR → Workshop IR lowering boundary.
-//!
-//! Canonical Workshop IR ownership moved to `workshop-rs` (wright#143,
-//! ADR-0009): the `wir`, `settings`, and `source` models are no longer
-//! implemented here. The generic IR infrastructure they share (`ids`,
-//! `arena`, `format`, `error`) is re-exported from `workshop-rs` so the HIR
-//! and the Workshop IR it lowers into share one type identity. These
-//! re-export shims contain no independent implementation and disappear when
-//! the HIR and lowering extract to `opy-rs`; until then, canonical
-//! Workshop-type changes route to `workshop-rs`.
-//!
-//! The crate remains protocol-agnostic: it does not depend on the
-//! `wright/opy-hir` bridge types in `wright-core`, on OverPy, or on any other
-//! Wright tooling crate.
-
 pub mod arena;
 pub mod error;
 pub mod format;
diff --git a/crates/wright-ir/src/lower.rs b/crates/wright-ir/src/lower.rs
index f08d70d9..7ff3c729 100644
--- a/crates/wright-ir/src/lower.rs
+++ b/crates/wright-ir/src/lower.rs
@@ -220,7 +220,7 @@ impl<'a> Lowerer<'a> {
             self.subroutines.insert(id, wir_id);
         }
 
-        // Rules. Declaration initializers become synthetic
+        // Declaration initializers become synthetic
         // "Initialize global variables" / "Initialize player variables"
         // rules here, in the profile-independent lowering path, so
         // initialization semantics never depend on an optimization profile
@@ -436,9 +436,6 @@ impl<'a> Lowerer<'a> {
         let action = match &statement {
             Stmt::Expr { expr, .. } => match self.lower_expr_stmt_with(*expr, span, out, params)? {
                 Some(action) => action,
-                // The statement inlined into `out` (void-function call or a
-                // value-function call used for its side effects); nothing
-                // further to push.
                 None => return Ok(()),
             },
             Stmt::Assign { target, value, .. } => {
@@ -520,7 +517,6 @@ impl<'a> Lowerer<'a> {
                 *variable, *start, *condition, *step, body, span, out, params,
             )?,
             Stmt::Switch { value, cases, .. } => {
-                // Pushes the dispatch and every case body into `out`.
                 return self.lower_switch(*value, cases, span, out, params);
             }
             Stmt::Return { value, .. } => {
diff --git a/crates/wright-language/src/document.rs b/crates/wright-language/src/document.rs
index 01dbe885..a9fdfc8b 100644
--- a/crates/wright-language/src/document.rs
+++ b/crates/wright-language/src/document.rs
@@ -1,5 +1,3 @@
-//! The document/workspace model (#63).
-//!
 //! A [`Document`] is one open source file with a stable URI, its current
 //! text, and a monotonically increasing version assigned by the host on every
 //! change. A [`DocumentStore`] owns the workspace's open documents and the
@@ -163,8 +161,6 @@ impl DocumentStore {
     pub fn overlay(&self, root: &PathBuf) -> BTreeMap<String, String> {
         let mut overlay = BTreeMap::new();
         for document in self.documents.values() {
-            // Only overlay file-backed documents (skip synthetic/in-memory
-            // URIs without a filesystem path).
             let Some(path) = uri_to_path(&document.uri) else {
                 continue;
             };
diff --git a/crates/wright-language/src/lib.rs b/crates/wright-language/src/lib.rs
index 36c12d13..5017db02 100644
--- a/crates/wright-language/src/lib.rs
+++ b/crates/wright-language/src/lib.rs
@@ -1,13 +1,3 @@
-//! Wright's editor-neutral language-service core (issue #63).
-//!
-//! This crate owns language intelligence **without any LSP types**: a
-//! versioned [`Document`]/[`DocumentStore`] workspace model, editor-neutral
-//! requests and results (positions, ranges, diagnostics, hover, definition,
-//! references, completion, rename, semantic tokens), and a
-//! [`service::LanguageService`] that composes the native `.opy` frontend, the
-//! semantic index/analyzer, the safe-edit contract, and the workshop catalog.
-//! The LSP adapter (`wright-lsp`) is a thin mapping over these types.
-
 pub mod document;
 pub mod service;
 
diff --git a/crates/wright-language/src/service.rs b/crates/wright-language/src/service.rs
index 2d624bfe..406edfef 100644
--- a/crates/wright-language/src/service.rs
+++ b/crates/wright-language/src/service.rs
@@ -485,8 +485,6 @@ impl LanguageService {
         };
         let analysis = self.analyze(document);
 
-        // Position/context: the identifier being typed and whether the
-        // position follows a member-access dot.
         let prefix = word_prefix(&document.text, position);
         let member = member_receiver(&document.text, position);
 
diff --git a/crates/wright-lpp/src/client.rs b/crates/wright-lpp/src/client.rs
index f8f3e53e..d754c73a 100644
--- a/crates/wright-lpp/src/client.rs
+++ b/crates/wright-lpp/src/client.rs
@@ -1,5 +1,3 @@
-//! Newline-delimited JSON-RPC 2.0 client over a byte transport.
-//!
 //! This module owns the wire mechanics of the LPP client: newline-delimited
 //! framing (LF writes, LF/CRLF and empty-line-tolerant reads), correlation
 //! ids, request/response matching, request timeouts, the LPP session phase
diff --git a/crates/wright-lpp/src/error.rs b/crates/wright-lpp/src/error.rs
index 1c7b356c..a0917e15 100644
--- a/crates/wright-lpp/src/error.rs
+++ b/crates/wright-lpp/src/error.rs
@@ -1,5 +1,3 @@
-//! Structured client failures for LPP interactions.
-//!
 //! Every provider interaction fails deterministically into one of the
 //! [`ProviderError`] variants below. Each variant exposes a stable machine
 //! `code()` and a human-readable `Display`, so tooling layers can surface
diff --git a/crates/wright-lpp/src/lib.rs b/crates/wright-lpp/src/lib.rs
index f855bf88..f3ab7217 100644
--- a/crates/wright-lpp/src/lib.rs
+++ b/crates/wright-lpp/src/lib.rs
@@ -1,35 +1,9 @@
-//! Wright's Language Provider Protocol (LPP) v1 client (#142).
-//!
 //! This crate is the Wright-owned client/runtime side of the Language
 //! Provider Protocol. The wire contract itself — message shapes, methods,
 //! error kinds, and conformance fixtures — is owned by the
 //! `language-provider-protocol` repository (spec/lpp-v1.md); this crate
 //! consumes that contract and never redefines it.
 //!
-//! # Layers
-//!
-//! ```text
-//! ToolService / language services
-//!         |
-//!         |  LanguageProvider (transport-neutral, language-neutral trait)
-//!         v
-//!  StdioLanguageProvider    -- capability guards, typed LPP data mapping
-//!         |
-//!         |  JsonRpcClient   -- framing, correlation, timeouts, session phase
-//!         v
-//!  ChildProcess             -- spawn/kill/wait a long-running stdio provider
-//!         |
-//!         v
-//!  a provider binary (any source language; the conformance reference
-//!  provider serves the deliberately foreign `x-demo-lang` language)
-//! ```
-//!
-//! `StdioLanguageProvider` implements the [`LanguageProvider`] trait, which
-//! is the stable seam ToolService and language services consume. The trait
-//! exposes provider capabilities and source-oriented operations only; JSON-
-//! RPC framing, correlation ids, process handles, and timeouts stay below
-//! it.
-//!
 //! # Language neutrality
 //!
 //! Nothing in this crate branches on a particular source language. Providers
diff --git a/crates/wright-lpp/src/process.rs b/crates/wright-lpp/src/process.rs
index 112f8b68..0665cbfb 100644
--- a/crates/wright-lpp/src/process.rs
+++ b/crates/wright-lpp/src/process.rs
@@ -1,6 +1,3 @@
-//! The stdio process adapter: spawn, observe, and terminate a long-running
-//! LPP provider binary.
-//!
 //! LPP is a process boundary: the client spawns the provider as a child
 //! process and communicates over its standard input and output. The
 //! provider's standard error is reserved for human-readable logging and
diff --git a/crates/wright-lpp/src/provider.rs b/crates/wright-lpp/src/provider.rs
index e949fb26..ce3016d5 100644
--- a/crates/wright-lpp/src/provider.rs
+++ b/crates/wright-lpp/src/provider.rs
@@ -1,5 +1,3 @@
-//! The transport-neutral provider abstraction and its stdio implementation.
-//!
 //! [`LanguageProvider`] is the stable seam that ToolService and language
 //! services consume: provider capabilities plus source-oriented operations,
 //! with no process, framing, or JSON-RPC details exposed. Failures surface
diff --git a/crates/wright-lpp/src/registry.rs b/crates/wright-lpp/src/registry.rs
index 9c3e030c..bd5dbf68 100644
--- a/crates/wright-lpp/src/registry.rs
+++ b/crates/wright-lpp/src/registry.rs
@@ -1,5 +1,3 @@
-//! Provider discovery and configuration by opaque language id.
-//!
 //! A [`ProviderRegistry`] maps opaque language id strings to provider
 //! configurations. Nothing in this module (or elsewhere in the crate)
 //! branches on a particular source language: `x-demo-lang` or any other id
diff --git a/crates/wright-lpp/src/types.rs b/crates/wright-lpp/src/types.rs
index cb10580a..f7b6a7e1 100644
--- a/crates/wright-lpp/src/types.rs
+++ b/crates/wright-lpp/src/types.rs
@@ -1,5 +1,3 @@
-//! LPP v1 data types used by the client.
-//!
 //! These types mirror the wire shapes defined in the `language-provider-
 //! protocol` repository's LPP v1 specification (sections 6-17). The wire
 //! contract is normative there; this module is the client-side Rust view of
diff --git a/crates/wright-lsp/src/main.rs b/crates/wright-lsp/src/main.rs
index dab3e08e..f664ae21 100644
--- a/crates/wright-lsp/src/main.rs
+++ b/crates/wright-lsp/src/main.rs
@@ -1,5 +1,3 @@
-//! `wright-lsp` — the Wright language server (issue #67).
-//!
 //! A thin LSP protocol adapter over [`wright_language::LanguageService`]:
 //! all semantic logic lives in the editor-neutral service crate; this
 //! binary only maps LSP DTOs to and from it, handles the stdio
diff --git a/crates/wright-opy/src/lib.rs b/crates/wright-opy/src/lib.rs
index ef120707..1378d92f 100644
--- a/crates/wright-opy/src/lib.rs
+++ b/crates/wright-opy/src/lib.rs
@@ -1,9 +1,3 @@
-//! Narrow Wright adapter for the owner-side `opy-rs` implementation.
-//!
-//! This crate owns no OPY parsing, semantic resolution, HIR, manifest, or
-//! reconstruction rules. It preserves the historical Wright-facing boundary
-//! while delegating those capabilities to `opy-rs`.
-
 pub use opy_rs::{cst, diag, lexer, parser, preprocess, settings, support, tooling};
 
 pub mod manifest {
diff --git a/crates/wright-ostw/src/lib.rs b/crates/wright-ostw/src/lib.rs
index 8908fcd5..0c99efef 100644
--- a/crates/wright-ostw/src/lib.rs
+++ b/crates/wright-ostw/src/lib.rs
@@ -1,9 +1,3 @@
-//! Narrow Wright adapter for the owner-side `del-rs` implementation.
-//!
-//! `del-rs` owns OSTW/DeltinScript parsing, project loading, semantic
-//! analysis, lowering, diagnostics, and reconstruction. This crate only maps
-//! those owner contracts to the historical Wright driver boundaries.
-
 use std::path::{Path, PathBuf};
 
 use workshop_rs::source::{FileId as WorkshopFileId, Position, Span};
diff --git a/crates/wright-transform/src/fold_constants.rs b/crates/wright-transform/src/fold_constants.rs
index 8886dedd..c2c7e1b0 100644
--- a/crates/wright-transform/src/fold_constants.rs
+++ b/crates/wright-transform/src/fold_constants.rs
@@ -1,5 +1,3 @@
-//! The `fold-constants` compat pass.
-//!
 //! Folds constant expressions in place: `2 * 3` → `6`, `-5` → the literal
 //! `-5`, `sqrt(4)` → `2`, `1 < 2` → `True`, and boolean logic on literals.
 //! This is exactly the arithmetic the pinned OverPy reference folds before
diff --git a/crates/wright-transform/src/lib.rs b/crates/wright-transform/src/lib.rs
index 1542e640..09184f21 100644
--- a/crates/wright-transform/src/lib.rs
+++ b/crates/wright-transform/src/lib.rs
@@ -1,5 +1,3 @@
-//! WIR transformation pipeline (issues #51/#52).
-//!
 //! Transformations live in an explicit, validated pass pipeline separate from
 //! read-only analysis and backend emission. Profiles select the pass set:
 //!
diff --git a/crates/wright-transform/src/pipeline.rs b/crates/wright-transform/src/pipeline.rs
index 61545191..a251a122 100644
--- a/crates/wright-transform/src/pipeline.rs
+++ b/crates/wright-transform/src/pipeline.rs
@@ -1,5 +1,3 @@
-//! The pass pipeline: ordering, profiles, metrics, and validation.
-
 use workshop_rs::wir;
 
 use crate::fold_constants::FoldConstants;
diff --git a/crates/wright-transform/src/profile.rs b/crates/wright-transform/src/profile.rs
index 4ca0a3db..a6e7bc4b 100644
--- a/crates/wright-transform/src/profile.rs
+++ b/crates/wright-transform/src/profile.rs
@@ -1,5 +1,3 @@
-//! Transformation profiles.
-
 use serde::{Deserialize, Serialize};
 
 /// The transformation policy for a session.