Completion, docs, and command debugging

Cobra adds a default completion command when the root executes. With subcommands it is listed in help. A root without subcommands still intercepts the word completion as its first argument, so its RunE never receives that value. Control this with root.CompletionOptions.DisableDefaultCmd and HiddenDefaultCmd, and check existing behavior before adding another generator. It supports Bash, Zsh, Fish, and PowerShell; write scripts on explicit request rather than silently editing shell startup files.

• Static positional choices: ValidArgs; pair with cobra.OnlyValidArgs if invalid values must also be rejected. Completion is not validation.
• Dynamic positional choices: ValidArgsFunction.
• Flag values: RegisterFlagCompletionFunc, after the flag exists. Check its returned error. The command handler must still validate values independently.
• Use cobra.ShellCompDirectiveNoFileComp for repo IDs, names, and tags so the shell does not add unrelated filesystem suggestions. For path flags, use MarkFlagFilename(name, "yaml", "yml") or MarkFlagDirname(name); these set the ShellCompDirectiveFilterFileExt and ShellCompDirectiveFilterDirs directives, which are constants, not functions.
• Completion callbacks should be read-only and fast. Prefer a local snapshot over a network scan or exclusive database lock. Errors should return the appropriate directive, not prose on completion stdout.
• Test the completion protocol, e.g. root.SetArgs([]string{"__complete", "list", "--tag", "g"}), using a new tree and captured output. Stdout holds one candidate per line, then :<directive>. Check the candidates and directive; do not hardcode incidental help wording. The --tag completion in commands.md has such a test.
• A root PersistentPreRunE runs for completion <shell> and every __complete request. Keep config loading out of it, or completion fails wherever the config is missing or invalid.

Documentation generation is in github.com/spf13/cobra/doc, e.g. doc.GenMarkdownTree(root, outputDir) and doc.GenManTree(root, header, outputDir), where header is a *doc.GenManHeader with the title, section, and date. Generate from the same command constructors used by the binary. For reproducible output, set root.DisableAutoGenTag = true to drop the "Auto generated by spf13/cobra" footer and its date, give the man header a fixed Date and a Source, and compare output intentionally.

When a flag or hook behaves unexpectedly:

1. Inspect the actual leaf selected by ExecuteC/ExecuteContextC.
2. Check local vs persistent flags, duplicate names/shorthands, and whether a child shadows an ancestor's flag.
3. Check Changed, parsing boundaries (--), positional arguments, and the difference between StringArray and StringSlice.
4. Inspect nearest persistent hooks. Root setup can be skipped by a child hook.
5. Check whether a config binding references the correct flag object. Do not reuse one Viper instance across command trees with conflicting flag names.

Pinned sources: completion guide, completion implementation, documentation generators.