Add verbose file change reporting

Author: theletterf

README.md

@@ -55,6 +55,9 @@ installs Vale when needed and configures the Elastic rules. Use
 are explicit because the upstream installers can install system tools and may
 ask before replacing existing local configuration.
 
+See the [command and managed-locations reference](docs/reference.md) for
+`--verbose`, configuration paths, and optional-tool locations.
+
 ## What it manages
 
 - Canonical skills at `~/.agents/skills`; Claude Code and Cursor receive links

cmd/elastic-docs-utils/main.go

@@ -37,7 +37,8 @@ import (
 var Version = "dev"
 
 type globalFlags struct {
-	color string
+	color   string
+	verbose bool
 }
 
 func main() {
@@ -54,6 +55,7 @@ func run(args []string) error {
 		return err
 	}
 	renderer := ui.New(ui.ColorMode(global.color), os.Stdout, os.Stderr)
+	renderer.SetVerbose(global.verbose)
 	if len(args) == 0 {
 		return commandInstall(renderer, nil)
 	}
@@ -89,6 +91,11 @@ func run(args []string) error {
 func parseGlobal(args []string, flags *globalFlags) ([]string, error) {
 	remaining := make([]string, 0, len(args))
 	for len(args) > 0 {
+		if args[0] == "--verbose" {
+			flags.verbose = true
+			args = args[1:]
+			continue
+		}
 		if !strings.HasPrefix(args[0], "--color") {
 			remaining, args = append(remaining, args[0]), args[1:]
 			continue
@@ -153,6 +160,9 @@ func commandInstall(r *ui.Renderer, args []string) error {
 		if err := state.SavePreferences(state.Preferences{Hosts: hosts.Strings(ids), Internal: *internal}); err != nil {
 			return err
 		}
+		if path, err := paths.PreferencesPath(); err == nil {
+			r.Verbose("Updated preferences: %s", path)
+		}
 		if err := refreshUpdates(r); err != nil {
 			return err
 		}
@@ -183,12 +193,14 @@ func installOptionalTools(r *ui.Renderer, vale, docsBuilder, dryRun bool) error
 	}
 	if vale {
 		r.Info("Installing Vale and Elastic Vale rules.")
+		r.Verbose("Runs the upstream Elastic Vale Rules installer; it reports the Vale binary, configuration, and rule paths it edits.")
 		if err := bootstrap.InstallVale(); err != nil {
 			return fmt.Errorf("install Vale and Elastic Vale rules: %w", err)
 		}
 	}
 	if docsBuilder {
 		r.Info("Installing docs-builder.")
+		r.Verbose("Runs the upstream docs-builder installer; it reports the binary path it edits.")
 		if err := bootstrap.InstallDocsBuilder(); err != nil {
 			return fmt.Errorf("install docs-builder: %w", err)
 		}
@@ -469,27 +481,44 @@ func synchronize(ids []hosts.ID, internal, dryRun, force bool, r *ui.Renderer) e
 	}
 	if dryRun {
 		r.Info("Would refresh public%s skills in ~/.agents/skills.", map[bool]string{true: " and internal", false: ""}[internal])
+		if root, err := paths.CanonicalSkillsDir(); err == nil {
+			r.Verbose("Would refresh managed skills beneath: %s", root)
+		}
 	} else {
 		r.Success("Installed %d managed skills.", len(skillResult.Installed))
+		for _, path := range skillResult.Files {
+			r.Verbose("Updated managed skill or discovery link: %s", path)
+		}
 	}
 	r.Section("Synchronizing host adapters")
 	adapterResult, err := adapters.Sync(ids, internal, dryRun, force)
 	if err != nil {
 		return err
 	}
 	if dryRun {
+		for name, host := range adapterResult.Hosts {
+			for _, path := range host.Files {
+				r.Verbose("Would update %s configuration: %s", name, path)
+			}
+		}
 		r.Info("Would configure %d selected host adapters.", len(ids))
 		return nil
 	}
 	for name, host := range adapterResult.Hosts {
 		s.Hosts[name] = host
+		for _, path := range host.Files {
+			r.Verbose("Updated %s configuration: %s", name, path)
+		}
 	}
 	for name, record := range skillResult.Records {
 		s.Skills[name] = record
 	}
 	if err := state.Save(s); err != nil {
 		return err
 	}
+	if path, err := paths.StatePath(); err == nil {
+		r.Verbose("Updated managed state: %s", path)
+	}
 	for _, warning := range adapterResult.Warnings {
 		r.Warn("%s", warning)
 	}
@@ -529,5 +558,6 @@ Commands:
 
 Global options:
   --color auto|always|never
+  --verbose                 Show managed file locations that are changed
 `)
 }

docs/reference.md

@@ -0,0 +1,49 @@
+# Elastic Docs Utils reference
+
+## Global options
+
+| Option | Meaning |
+|---|---|
+| `--color auto\|always\|never` | Control ANSI color output. |
+| `--verbose` | Print every Elastic Docs Utils-managed file or directory changed by a mutating command. It prints paths only, never configuration values or secrets. |
+
+Global options can appear before or after the command:
+
+```bash
+elastic-docs-utils --verbose install --with-vale
+elastic-docs-utils install --verbose --with-docs-builder
+```
+
+## Managed locations
+
+| Purpose | Location |
+|---|---|
+| Preferences | macOS/Linux: OS config directory under `elastic/docs-utils/config.json`; Windows: `%AppData%\elastic\docs-utils\config.json` |
+| Managed state | macOS/Linux: OS config directory under `elastic/docs-utils/state.json`; Windows: `%AppData%\elastic\docs-utils\state.json` |
+| Update cache | OS cache directory under `elastic/docs-utils/update-status.json` |
+| Shared skills | `~/.agents/skills/<skill>` |
+| Claude Code MCP | `~/.claude.json` |
+| Claude Code session hook | `~/.claude/settings.json` |
+| Codex MCP | `~/.codex/config.toml` |
+| Cursor CLI MCP | `~/.cursor/mcp.json` |
+| OpenCode MCP | macOS/Linux: `~/.config/opencode/opencode.json`; Windows: the OS config directory under `opencode/opencode.json` |
+
+Claude Code and Cursor CLI receive skill discovery links below their respective
+`~/.claude/skills` and `~/.cursor/skills` directories. Existing non-Elastic
+configuration is retained unless `--force` is explicitly supplied for a
+conflicting Elastic Docs MCP entry.
+
+## Optional documentation tools
+
+`install --with-vale` runs the maintained Elastic Vale Rules platform
+installer. It may install the Vale binary and manages the following locations:
+
+| Platform | Vale configuration | Elastic styles |
+|---|---|---|
+| macOS | `~/Library/Application Support/vale/.vale.ini` | `~/Library/Application Support/vale/styles/Elastic` |
+| Linux | `~/.config/vale/.vale.ini` | `~/.local/share/vale/styles/Elastic` (or XDG overrides) |
+| Windows | `%LOCALAPPDATA%\vale\.vale.ini` | `%LOCALAPPDATA%\vale\styles\Elastic` |
+
+`install --with-docs-builder` runs the maintained Docs Builder installer. Its
+installation location is chosen by that upstream script and is printed by the
+script while it runs.

internal/adapters/adapters.go

@@ -114,7 +114,7 @@ func Sync(targets []hosts.ID, internal, dryRun, force bool) (Result, error) {
 		case hosts.Claude:
 			files, err = addClaude(internal, dryRun)
 		case hosts.Codex:
-			err = addCodex(internal, dryRun)
+			files, err = addCodex(internal, dryRun)
 		case hosts.Cursor:
 			files, err = writeCursor(internal, dryRun, force)
 		case hosts.OpenCode:
@@ -185,6 +185,10 @@ func servers(internal bool) []struct{ name, url string } {
 }
 
 func addClaude(internal, dryRun bool) ([]string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, err
+	}
 	for _, server := range servers(internal) {
 		if dryRun {
 			continue
@@ -193,29 +197,30 @@ func addClaude(internal, dryRun bool) ([]string, error) {
 			return nil, err
 		}
 	}
-	path, err := claudeHookPath()
-	if err != nil {
-		return nil, err
-	}
+	path := filepath.Join(home, ".claude", "settings.json")
 	if dryRun {
-		return []string{path}, nil
+		return []string{filepath.Join(home, ".claude.json"), path}, nil
 	}
 	if err := writeClaudeHook(path); err != nil {
 		return nil, err
 	}
-	return []string{path}, nil
+	return []string{filepath.Join(home, ".claude.json"), path}, nil
 }
 
-func addCodex(internal, dryRun bool) error {
+func addCodex(internal, dryRun bool) ([]string, error) {
 	for _, server := range servers(internal) {
 		if dryRun {
 			continue
 		}
 		if err := runAdd("codex", "mcp", "add", server.name, "--url", server.url); err != nil {
-			return err
+			return nil, err
 		}
 	}
-	return nil
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, err
+	}
+	return []string{filepath.Join(home, ".codex", "config.toml")}, nil
 }
 
 func runAdd(command string, args ...string) error {

internal/skills/skills.go

@@ -41,6 +41,7 @@ type Result struct {
 	Installed []string
 	Linked    []string
 	Records   map[string]state.SkillState
+	Files     []string
 }
 
 // Sync fetches enabled catalogs, installs all skills into ~/.agents/skills,
@@ -79,6 +80,7 @@ func Sync(targets []hosts.ID, internal, dryRun bool) (Result, error) {
 			}
 			result.Installed = append(result.Installed, name)
 			result.Records[name] = state.SkillState{Source: repo, Commit: commit}
+			result.Files = append(result.Files, destination)
 		}
 		if err := os.RemoveAll(staging); err != nil {
 			return result, err
@@ -93,10 +95,12 @@ func Sync(targets []hosts.ID, internal, dryRun bool) (Result, error) {
 	}
 	for _, id := range targets {
 		for _, target := range linkRoots(id) {
-			if err := linkAll(root, target); err != nil {
+			links, err := linkAll(root, target)
+			if err != nil {
 				return result, err
 			}
 			result.Linked = append(result.Linked, string(id))
+			result.Files = append(result.Files, links...)
 		}
 	}
 	return result, nil
@@ -255,14 +259,15 @@ func linkRoots(id hosts.ID) []string {
 	}
 }
 
-func linkAll(source, target string) error {
+func linkAll(source, target string) ([]string, error) {
 	if err := os.MkdirAll(target, 0o755); err != nil {
-		return err
+		return nil, err
 	}
 	entries, err := os.ReadDir(source)
 	if err != nil {
-		return err
+		return nil, err
 	}
+	links := []string{}
 	for _, entry := range entries {
 		if !entry.IsDir() {
 			continue
@@ -273,11 +278,12 @@ func linkAll(source, target string) error {
 		}
 		if err := os.Symlink(filepath.Join(source, entry.Name()), link); err != nil {
 			if err := copyDir(filepath.Join(source, entry.Name()), link); err != nil {
-				return err
+				return nil, err
 			}
 		}
+		links = append(links, link)
 	}
-	return nil
+	return links, nil
 }
 
 // RemoveOwned deletes only skill directories carrying this product's marker.

internal/ui/ui.go

@@ -35,11 +35,15 @@ const (
 // Renderer renders human-readable command output. JSON-producing callers do
 // not use this type.
 type Renderer struct {
-	out   io.Writer
-	err   io.Writer
-	color bool
+	out     io.Writer
+	err     io.Writer
+	color   bool
+	verbose bool
 }
 
+// SetVerbose enables diagnostic file-change output for mutating commands.
+func (r *Renderer) SetVerbose(enabled bool) { r.verbose = enabled }
+
 // New creates a renderer. ColorAuto honors NO_COLOR, TERM=dumb, and whether
 // stdout is an interactive terminal.
 func New(mode ColorMode, out, errOut io.Writer) *Renderer {
@@ -120,6 +124,15 @@ func (r *Renderer) Info(format string, args ...any) {
 	fmt.Fprintf(r.out, "%s %s\n", r.paint("36;1", "[INFO]"), fmt.Sprintf(format, args...))
 }
 
+// Verbose describes an owned file or configuration location changed by a
+// command. It never prints secrets or configuration contents.
+func (r *Renderer) Verbose(format string, args ...any) {
+	if !r.verbose {
+		return
+	}
+	fmt.Fprintf(r.out, "%s %s\n", r.paint("90", "[VERBOSE]"), fmt.Sprintf(format, args...))
+}
+
 func (r *Renderer) Success(format string, args ...any) {
 	fmt.Fprintf(r.out, "%s %s\n", r.paint("32;1", "[OK]"), fmt.Sprintf(format, args...))
 }