Getting Started: `complyctl init` documentation does not match observed behavior

[trevor-vaughan]

Summary

The getting-started description of complyctl init is wrong on three points: the config
file location, the re-run behavior, and the fact that the command is interactive. Step 1 of
the quick start therefore sets a false mental model for everything that follows.

Affected

• Page: content/docs/getting-started/_index.md (lines 91–94)

Documented behavior

"1. Initialize a workspace … Creates a complytime.yaml workspace config. If one
already exists, it validates and runs get automatically."

Observed behavior

$ complyctl init
Add policies (one per line). For each, enter the OCI URL and an optional short ID.
Press Enter with an empty URL to finish.
  Policy 1 URL (e.g. registry.com/policies/nist-800-53-r5@v1.0): Workspace configuration created ...
$ ls complytime.yaml
ls: cannot access 'complytime.yaml': No such file or directory
$ find . -name '*.yaml'
./.complytime/complytime.yaml

The three drifts

1. Location. The page says it creates complytime.yaml at the top level. It actually
   creates ./.complytime/complytime.yaml inside a hidden subdirectory. doctor confirms
   the real path (config: …/.complytime/complytime.yaml not found). The generated file's
   own header comment and the success message both say complytime.yaml, pointing at a path
   that does not exist as written.

2. Re-run behavior. The page promises that if a config exists, init "validates and
   runs get automatically." Observed:

   $ complyctl init     # second time
   Error: …/.complytime/complytime.yaml already exists   (exit 1)
   

   It refuses — no validate, no auto-get. (The create-only behavior is reasonable in
   itself; the issue is that the docs describe something the tool does not do.)

3. Interactivity, undocumented. The page shows complyctl init as a silent one-liner.
   It is an interactive prompt ("Policy 1 URL …"). Anyone scripting this in CI per the page
   will hang on stdin.

Suggested fix

Make the prose match the binary: name the real path (.complytime/complytime.yaml),
describe the interactive prompt and document a non-interactive form suitable for CI, and
remove the "re-run validates and runs get" sentence (or align it with the actual
create-only behavior).

Issue created with the help of Claude Opus 4.6