diff --git a/README.md b/README.md
index d8ee492..ccba27f 100644
--- a/README.md
+++ b/README.md
@@ -156,8 +156,8 @@ remetric scan \
   --grafana http://localhost:3000
 ```
 
-`scan` emits a `findings.Report` (see spec §5.5) - combine with `--output json`
-for CI.
+`scan` emits a `findings.Report` envelope (target, overview, findings,
+warnings) - combine with `--output json` for CI.
 
 ## VictoriaMetrics support
 
diff --git a/internal/analyzers/labelpattern/patterns.go b/internal/analyzers/labelpattern/patterns.go
index 3fc0b2d..fe34d45 100644
--- a/internal/analyzers/labelpattern/patterns.go
+++ b/internal/analyzers/labelpattern/patterns.go
@@ -7,8 +7,8 @@ package labelpattern
 
 import "regexp"
 
-// defaultPatternSources are the verbatim regex patterns from the spec
-// (§6.3). Compiled lazily via DefaultPatterns.
+// defaultPatternSources are the high-cardinality label-name patterns
+// the analyzer flags by default. Compiled lazily via DefaultPatterns.
 var defaultPatternSources = []string{
 	`(?i).*(uuid|guid).*`,
 	`(?i).*_id$`,
diff --git a/internal/cli/render.go b/internal/cli/render.go
index bca6c13..f4c838f 100644
--- a/internal/cli/render.go
+++ b/internal/cli/render.go
@@ -51,7 +51,7 @@ func validateOutput(s string) error {
 
 // renderReport dispatches Report rendering based on cfg.Output.
 // Terminal output prints any Warnings as a yellow banner above the
-// findings table. JSON emits the full §5.5 envelope.
+// findings table. JSON emits the full Report envelope.
 //
 // renderReport populates Finding.DocURL from Finding.Class for every
 // finding in rep that has a Class but no caller-provided DocURL. The fill
diff --git a/internal/findings/severity.go b/internal/findings/severity.go
index f77c10c..068bda8 100644
--- a/internal/findings/severity.go
+++ b/internal/findings/severity.go
@@ -57,8 +57,8 @@ func ParseSeverity(s string) (Severity, error) {
 	return 0, fmt.Errorf("unknown severity %q", s)
 }
 
-// MarshalJSON encodes the severity as a lower-case string,
-// matching the JSON schema in the spec (§5.5).
+// MarshalJSON encodes the severity as a lower-case string
+// (critical|high|medium|low) for the public JSON wire form.
 func (s Severity) MarshalJSON() ([]byte, error) {
 	return json.Marshal(s.lower())
 }
diff --git a/internal/output/json/json.go b/internal/output/json/json.go
index 86f1bc0..0d90a6d 100644
--- a/internal/output/json/json.go
+++ b/internal/output/json/json.go
@@ -45,7 +45,8 @@ func (r *Renderer) RenderFindingsWithIgnored(fs []findings.Finding, ignored int)
 	return r.encode(envelope)
 }
 
-// RenderReport emits the full §5.5 schema.
+// RenderReport emits the full Report envelope (target, overview,
+// findings, warnings, ignored_count, scanned_at).
 func (r *Renderer) RenderReport(rep *findings.Report) error {
 	if rep == nil {
 		return fmt.Errorf("output/json: nil report")