INF-1307 rescue cmd/twoctl/ + add shell completion guidance

The .gitignore had an unanchored `twoctl` line that matched both the
binary AND the cmd/twoctl/ source dir, so the initial scaffold + two
follow-up commits silently shipped without any of the CLI code. The
repo on GitHub built only because no test referenced it - go test on
internal packages still passed.

This commit:
- anchors .gitignore (/twoctl) so the dir is no longer matched
- restores every cmd/twoctl/ source file (auth, root, operations,
  catalog, upgrade, errors, main, tests, embedded specs)
- registers shell completions for enum-valued parameters via cobra's
  RegisterFlagCompletionFunc - tab-completion now suggests valid
  values for country codes, currencies, statuses etc.
- calls MarkFlagRequired on required parameters so cobra rejects
  missing inputs with a clear usage error before the RunE fires
- documents shell-completion setup for bash, zsh, fish, powershell

Author: brtkwr

.gitignore

@@ -1,6 +1,6 @@
 /dist/
 /bin/
-twoctl
+/twoctl
 *.test
 *.out
 .DS_Store

README.md

@@ -20,6 +20,68 @@ Download from [releases](https://github.com/two-inc/twoctl/releases) and place o
 go install github.com/two-inc/twoctl/cmd/twoctl@latest
 ```
 
+## Shell completion
+
+`twoctl` ships completions for bash, zsh, fish, and PowerShell. The binary
+generates them on demand via `twoctl completion <shell>`.
+
+### bash
+
+Linux:
+
+```sh
+twoctl completion bash | sudo tee /etc/bash_completion.d/twoctl > /dev/null
+```
+
+macOS (with `bash-completion@2` from Homebrew):
+
+```sh
+twoctl completion bash > "$(brew --prefix)/etc/bash_completion.d/twoctl"
+```
+
+If you don't have write access to a system path, source the completion in your
+`~/.bashrc`:
+
+```sh
+echo 'source <(twoctl completion bash)' >> ~/.bashrc
+```
+
+### zsh
+
+```sh
+# one-shot (re-run on shell start):
+echo 'source <(twoctl completion zsh)' >> ~/.zshrc
+
+# or persist to fpath:
+twoctl completion zsh > "${fpath[1]}/_twoctl"
+```
+
+If `compinit` hasn't been initialised in your `~/.zshrc`, add:
+
+```sh
+autoload -Uz compinit && compinit
+```
+
+before the completion source line.
+
+### fish
+
+```sh
+twoctl completion fish | source                                # current shell
+twoctl completion fish > ~/.config/fish/completions/twoctl.fish # persistent
+```
+
+### PowerShell
+
+```powershell
+twoctl completion powershell | Out-String | Invoke-Expression                          # current session
+twoctl completion powershell >> $PROFILE                                                # persistent
+```
+
+After installing, open a new shell. Tab-completion works on subcommands,
+flags, and any flag value that has a known enum in the OpenAPI spec
+(country codes, currencies, statuses).
+
 ## Authenticate
 
 `twoctl` reads your API key from (in order):

cmd/twoctl/cli/auth.go

@@ -0,0 +1,131 @@
+package cli
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+
+	"github.com/two-inc/twoctl/internal/config"
+)
+
+func init() {
+	authCmd := &cobra.Command{
+		Use:   "auth",
+		Short: "Manage API key authentication",
+	}
+	authCmd.AddCommand(
+		authLoginCmd(),
+		authLogoutCmd(),
+		authWhoamiCmd(),
+	)
+	register(authCmd)
+}
+
+func authLoginCmd() *cobra.Command {
+	var keyFlag string
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Store an API key in the OS keychain",
+		Long: `Store a Two API key in the OS keychain (macOS Keychain, GNOME Keyring,
+Windows Credential Manager). The key is read from --key, or prompted for
+interactively if not provided.
+
+twoctl prefers the keychain over the TWO_API_KEY environment variable when
+both are set.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			key := strings.TrimSpace(keyFlag)
+			if key == "" {
+				k, err := promptAPIKey(cmd)
+				if err != nil {
+					return err
+				}
+				key = k
+			}
+			if !looksLikeAPIKey(key) {
+				return fmt.Errorf("that does not look like a Two API key (expected prefix secret_test_ or secret_prod_)")
+			}
+			if err := config.StoreKey(key); err != nil {
+				return fmt.Errorf("storing key in keychain: %w", err)
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), "stored API key in OS keychain")
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&keyFlag, "key", "", "API key to store (will prompt if omitted)")
+	return cmd
+}
+
+func authLogoutCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "logout",
+		Short: "Remove the API key from the OS keychain",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := config.DeleteKey(); err != nil {
+				return fmt.Errorf("removing key: %w", err)
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), "removed cached API key")
+			return nil
+		},
+	}
+}
+
+func authWhoamiCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "whoami",
+		Short: "Show which API key and environment will be used",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			resolved, err := config.Resolve(flagAPIKey, flagEnv)
+			if err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "environment: %s (%s)\nkey source:  %s\nkey prefix:  %s\n",
+				resolved.Env, resolved.Env.BaseURL(), resolved.Source, redact(resolved.APIKey))
+			return nil
+		},
+	}
+}
+
+func promptAPIKey(cmd *cobra.Command) (string, error) {
+	fmt.Fprint(cmd.OutOrStdout(), "Two API key: ")
+	if term.IsTerminal(int(os.Stdin.Fd())) {
+		b, err := term.ReadPassword(int(os.Stdin.Fd()))
+		fmt.Fprintln(cmd.OutOrStdout())
+		if err != nil {
+			return "", err
+		}
+		return strings.TrimSpace(string(b)), nil
+	}
+	r := bufio.NewReader(os.Stdin)
+	line, err := r.ReadString('\n')
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(line), nil
+}
+
+func looksLikeAPIKey(s string) bool {
+	return strings.HasPrefix(s, "secret_test_") ||
+		strings.HasPrefix(s, "secret_prod_") ||
+		strings.HasPrefix(s, "secret_live_") ||
+		strings.HasPrefix(s, "secret_sandbox_")
+}
+
+// redact returns a key with everything between the env prefix and the last
+// four characters replaced by asterisks. Used for whoami output only.
+func redact(key string) string {
+	if len(key) < 16 {
+		return "****"
+	}
+	prefix := key
+	tail := key[len(key)-4:]
+	if idx := strings.Index(key, "_"); idx >= 0 {
+		if idx2 := strings.Index(key[idx+1:], "_"); idx2 >= 0 {
+			prefix = key[:idx+1+idx2+1]
+		}
+	}
+	return prefix + "****" + tail
+}

cmd/twoctl/cli/catalog.go

@@ -0,0 +1,114 @@
+package cli
+
+import (
+	"encoding/json"
+	"sort"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	cmd := &cobra.Command{
+		Use:   "catalog",
+		Short: "Print the full operation catalog as JSON for agent discovery",
+		Long: `Emit a machine-readable catalog of every operation twoctl knows about.
+
+Each entry includes the CLI command path, HTTP method, URL path template,
+summary, and the list of flags with their kind (path/query/header/body),
+type, and required status. Designed to be piped to an LLM or stored alongside
+agent prompts so the agent can plan calls without parsing --help text.`,
+		RunE: runCatalog,
+	}
+	cmd.Flags().StringP("api", "a", "", "limit catalog to a single API (checkout, billing-account, repay, recourse, company, limits)")
+	register(cmd)
+}
+
+type catalogFlag struct {
+	Name     string `json:"name"`
+	In       string `json:"in"`
+	Type     string `json:"type"`
+	Required bool   `json:"required"`
+	Desc     string `json:"description,omitempty"`
+}
+
+type catalogOp struct {
+	Command      string        `json:"command"`        // e.g. "twoctl checkout create-order"
+	API          string        `json:"api"`            // "checkout"
+	OperationID  string        `json:"operation_id,omitempty"`
+	Method       string        `json:"method"`
+	Path         string        `json:"path"`
+	Summary      string        `json:"summary,omitempty"`
+	Flags        []catalogFlag `json:"flags,omitempty"`
+	HasBody      bool          `json:"has_body"`
+	BodyRequired bool          `json:"body_required,omitempty"`
+}
+
+func runCatalog(cmd *cobra.Command, args []string) error {
+	wantAPI, _ := cmd.Flags().GetString("api")
+	var out []catalogOp
+
+	for _, m := range apiMeta {
+		if wantAPI != "" && wantAPI != m.use {
+			continue
+		}
+		raw, err := specFS.ReadFile("specs/" + m.file)
+		if err != nil {
+			return err
+		}
+		doc, err := openapi3.NewLoader().LoadFromData(raw)
+		if err != nil {
+			return err
+		}
+		for path, item := range doc.Paths.Map() {
+			for method, op := range item.Operations() {
+				if op == nil {
+					continue
+				}
+				name := commandNameFor(op, method, path)
+				for _, s := range stripSuffixes {
+					if len(name) > len(s) && name[len(name)-len(s):] == s {
+						name = name[:len(name)-len(s)]
+						break
+					}
+				}
+				entry := catalogOp{
+					Command:     "twoctl " + m.use + " " + name,
+					API:         m.use,
+					OperationID: op.OperationID,
+					Method:      method,
+					Path:        path,
+					Summary:     op.Summary,
+				}
+				for _, ref := range op.Parameters {
+					p := ref.Value
+					if p == nil {
+						continue
+					}
+					t := "string"
+					if p.Schema != nil && p.Schema.Value != nil && p.Schema.Value.Type != nil {
+						if s := p.Schema.Value.Type.Slice(); len(s) > 0 {
+							t = s[0]
+						}
+					}
+					entry.Flags = append(entry.Flags, catalogFlag{
+						Name:     toKebab(p.Name),
+						In:       p.In,
+						Type:     t,
+						Required: p.Required,
+						Desc:     p.Description,
+					})
+				}
+				if op.RequestBody != nil && op.RequestBody.Value != nil {
+					entry.HasBody = true
+					entry.BodyRequired = op.RequestBody.Value.Required
+				}
+				out = append(out, entry)
+			}
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Command < out[j].Command })
+	enc := json.NewEncoder(cmd.OutOrStdout())
+	enc.SetIndent("", "  ")
+	return enc.Encode(out)
+}