docs: Generate CLI reference docs for kagent and kmcp

[yashrajshuklaaa]

Closes #262.

What this does

Adds automated CLI reference doc generation for both kagent and kmcp, replacing kagent's hand written CLI pages and kmcp's flat manual pages. Wired into the existing update-ref-docs.yaml workflow, same as the API and Helm docs.

Why this approach

kagent and kmcp are not built the same way internally. kmcp exports its Cobra root command from a public package, so it could be documented natively using cobra/doc. kagent's root command sits inside package main and uses internal/ packages, so it cannot be imported from an external repo at all, this is a Go language restriction, not something fixable from the website side.

Since native generation is not available for both CLIs equally, this PR uses one approach for both: build the real binary in CI, then walk <binary> <path> --help recursively to reconstruct the full command tree. This is the same category of approach used in agentgateway/website's generate-agctl-ref.py, linked as prior art in the issue, though that script parses source statically while this one reads the actual compiled binary's output.

Calling --help recursively is safe, Cobra intercepts it before any PreRun/RunE hooks run, so no side effects like docker-compose or cluster calls get triggered during generation.

What is new

• scripts/generate-cli-docs.py: the generator script. Produces one Hugo page per command, matching the existing kagent-<command>.md naming style, with frontmatter, flags, subcommand links, and examples.
• scripts/audit-cli-docs.py: a small check script that verifies frontmatter, code fences, and section formatting before the generated pages get committed.
• Four new steps in .github/workflows/update-ref-docs.yaml: build each CLI binary, smoke test it with --help, then generate docs into the right content folders.

Content changes

• docs-site/content/kagent/resources/cli/: fully regenerated, as agreed in the issue. Nested subcommands now get their own pages instead of being folded into one parent page, so future subcommands get documented automatically.
• docs-site/content/kmcp/reference/: the 9 existing manual CLI pages moved into a new cli/ subfolder and are now generated, matching kagent's structure.
• kagent-help.md and kmcp-help.md removed, Cobra's built in help command has no real content of its own. completion is kept, since it documents actual shell specific subcommands that are genuinely useful.

Drift this caught

Regenerating from real --help output showed the old manual docs had gone stale in a few places:

• kagent deploy still documented --api-key/--api-key-secret, which do not exist anymore (--env-file replaced them)
• kagent invoke still documented --url-override, replaced by --token
• default model listed was gemini-2.0-flash, actual default is now gemini-2.5-flash

Known trade-off

The old kagent-mcp.md had hand written links to kmcp's dedicated reference pages. --help text cannot express that kind of cross-repo relationship, so those specific links are not present in the generated version. Happy to add them back manually if maintainers would like that.

Testing done

• Checked script output against the real --help text of both CLIs, not just a sample fixture. This caught and fixed a few real issues:
  • kmcp uses non standard header formatting in places (Available Commands:: with double colon, GlobalFlags: with no space), now handled
  • kagent's init command prints a duplicated Examples: section, only the first one is kept now
  • subcommand links initially pointed to raw .md filenames, which do not resolve under Hugo's URL scheme, fixed to use correct relative paths
  • the --config flag default was leaking the machine's actual home directory into the docs, now shown as the generic $HOME placeholder
• scripts/audit-cli-docs.py runs clean across all 61 generated pages
• Verified rendering locally with hugo server, including clicking through nested subcommand links

Follow ups (not blocking this PR)

• If kagent later exports its root command from a public package, it could switch to native cobra/doc generation like kmcp, without changing the page layout.
• The kagent-mcp.md cross-links mentioned above, if maintainers want them restored.

[yashrajshuklaaa]

cc @kristin-kronstain-brown PTAL

[yashrajshuklaaa]

All checks are green except "Preview / deploy" which looks like it needs Cloudflare secrets that aren't available to fork PRs, seems unrelated to the actual changes.