docs: document single-use command tree invariant

The builder's PreRunE mutates Cobra flag annotations to bypass
required-flag validation for --request-schema / --response-schema.
This is safe because each CLI invocation builds a fresh command tree.
Document this invariant in CLAUDE.md and AGENTS.md so future changes
don't accidentally introduce command reuse.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: somanshreddy

AGENTS.md

@@ -44,6 +44,9 @@ Files in `gen/` are deleted and regenerated by `make generate`. Never put hand-w
 ### `command.Spec` is immutable
 `Spec` is a generated, read-only definition. Never mutate it at runtime. Column definitions, poll configs, and other runtime enhancements are external lookup data in `cmd/heygen/`, passed to the formatter or builder as separate arguments.
 
+### Cobra command tree is single-use
+`newRootCmd()` builds a fresh Cobra command tree for each CLI invocation. Command instances are never reused across executions — each `main()` call and each test creates a new tree. This is load-bearing: the builder's `PreRunE` mutates Cobra flag annotations to bypass required-flag validation for `--request-schema` / `--response-schema`. If command reuse were ever introduced (e.g., embedding as a library), those mutations would leak between executions.
+
 ### Codegen requires examples
 `make generate` fails if any command lacks examples. Examples live in `codegen/examples/{group}.yaml`. When adding a new endpoint to the OpenAPI spec, add matching examples or codegen will reject it.
 

CLAUDE.md

@@ -42,6 +42,9 @@ Files in `gen/` are deleted and regenerated by `make generate`. Never put hand-w
 ### `command.Spec` is immutable
 `Spec` is a generated, read-only definition. Never mutate it at runtime. Column definitions, poll configs, and other runtime enhancements are external lookup data in `cmd/heygen/`, passed to the formatter or builder as separate arguments.
 
+### Cobra command tree is single-use
+`newRootCmd()` builds a fresh Cobra command tree for each CLI invocation. Command instances are never reused across executions — each `main()` call and each test creates a new tree. This is load-bearing: the builder's `PreRunE` mutates Cobra flag annotations to bypass required-flag validation for `--request-schema` / `--response-schema`. If command reuse were ever introduced (e.g., embedding as a library), those mutations would leak between executions.
+
 ### Codegen requires examples
 `make generate` fails if any command lacks examples. Examples live in `codegen/examples/{group}.yaml`. When adding a new endpoint to the OpenAPI spec, add matching examples or codegen will reject it.