diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
index 519da252..2b6ea6ae 100644
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -90,8 +90,12 @@ chunk init
 
 What it creates:
 
-- **`.chunk/config.json`** — list of validation commands (test, lint, format)
-- **`.claude/settings.json`** — hooks that run validation before commits and after each agent session
+- **`.chunk/config.json`** — list of validation commands (test, lint, format); tracked in git
+- **`.claude/settings.json`** — hooks that run validation before commits and after each agent session; tracked in git
+- **`.codex/hooks.json`** — the same hooks, for Codex sessions (only written if Codex is installed); tracked in git
+- **`.git/hooks/pre-commit`** — runs `chunk validate` locally before every commit; not tracked in git
+
+`chunk init` prints a one-line explanation after each of these hidden files so it's clear what got added and why.
 
 Review the generated config and adjust commands if needed:
 
diff --git a/internal/cmd/init.go b/internal/cmd/init.go
index f6344d77..2f07f5f1 100644
--- a/internal/cmd/init.go
+++ b/internal/cmd/init.go
@@ -72,6 +72,7 @@ func writeSettings(workDir string, commands []config.Command, streams iostream.S
 			}
 		}
 		streams.ErrPrintln(ui.Success("Wrote .claude/settings.json"))
+		streams.ErrPrintln(ui.Dim("  Hidden Claude Code config. Runs `chunk validate` before commits and after each agent session."))
 		return nil
 	}
 
@@ -124,6 +125,7 @@ func writeSettings(workDir string, commands []config.Command, streams iostream.S
 		}
 	}
 	streams.ErrPrintln(ui.Success("Updated .claude/settings.json"))
+	streams.ErrPrintln(ui.Dim("  Hidden Claude Code config. Runs `chunk validate` before commits and after each agent session."))
 	return nil
 }
 
@@ -177,6 +179,7 @@ func writeCodexHooks(workDir string, commands []config.Command, streams iostream
 			}
 		}
 		streams.ErrPrintln(ui.Success("Wrote .codex/hooks.json"))
+		streams.ErrPrintln(ui.Dim("  Hidden Codex config. Same hooks as .claude/settings.json, for Codex sessions."))
 		return nil
 	}
 
@@ -226,6 +229,7 @@ func writeCodexHooks(workDir string, commands []config.Command, streams iostream
 		}
 	}
 	streams.ErrPrintln(ui.Success("Updated .codex/hooks.json"))
+	streams.ErrPrintln(ui.Dim("  Hidden Codex config. Same hooks as .claude/settings.json, for Codex sessions."))
 	return nil
 }
 
@@ -367,6 +371,7 @@ func writeGitHook(gitCommonDir string, streams iostream.Streams) error {
 			}
 		}
 		streams.ErrPrintln(ui.Success("Wrote .git/hooks/pre-commit"))
+		streams.ErrPrintln(ui.Dim("  Not tracked in git. Runs `chunk validate` locally before every commit you make."))
 		return nil
 	}
 
@@ -392,6 +397,7 @@ func writeGitHook(gitCommonDir string, streams iostream.Streams) error {
 		}
 	}
 	streams.ErrPrintln(ui.Success("Updated .git/hooks/pre-commit"))
+	streams.ErrPrintln(ui.Dim("  Not tracked in git. Runs `chunk validate` locally before every commit you make."))
 	return nil
 }