Add a getting started guide for muster

[pipo02mix]

Towards https://github.com/giantswarm/giantswarm/issues/35651

[teemow]

Nice work on this getting-started guide, Fernando! The structure is clear, the ASCII architecture diagram is helpful, and the troubleshooting section covers the right scenarios. Here are my review notes:

Issues

1. muster context show requires a name argument

The command muster context show (line ~54 in the new file) will fail — it requires exactly one argument:

muster context show <name>

Either change it to muster context show my-platform or use muster context current (which takes no arguments and prints the current context name).

2. Redundancy between context setup (Step 2) and --endpoint in IDE config (Step 4)

Steps 2 and 3 walk the user through setting up a context (muster context add + muster context use) and authenticating. But then Step 4 passes --endpoint=https://... explicitly in the IDE's MCP config, which overrides the context entirely.

The muster agent command resolves endpoints with this precedence:

1. --endpoint flag
2. --context flag
3. MUSTER_CONTEXT env var
4. current-context from contexts.yaml

So the context setup in Step 2 becomes unused if --endpoint is always passed in the IDE config. I'd suggest one of:

• Option A (simpler): Remove Step 2 entirely and just use --endpoint everywhere. The user authenticates directly with muster auth login --endpoint https://....
• Option B (cleaner for multi-context users): Keep Steps 2-3 as-is, and remove --endpoint from the IDE config in Step 4, so it resolves from the active context. This is cleaner for users with multiple installations.

3. Grammar fix in prerequisites

"Have it configured dex in your management cluster(s) with the proper identity provider."

This reads awkwardly. Suggestion:

"Ensure dex is configured in your management cluster(s) with a supported identity provider. Contact our support team if this is not the case."

4. Meta-tool list is incomplete

"it exposes a small set of discovery and execution tools: list_tools, call_tool, filter_tools, and describe_tool"

The actual implementation exposes 11 meta-tools (including list_core_tools, list_resources, describe_resource, get_resource, list_prompts, describe_prompt, get_prompt). The simplification is fine for a getting-started guide, but the current phrasing reads as an exhaustive list. Consider changing to:

"it exposes a small set of meta-tools — including list_tools, call_tool, filter_tools, and describe_tool — that your AI assistant uses automatically."

5. Re-authentication description is slightly inaccurate

The session management section says:

"If your session expires, the agent detects it and prompts re-authentication."

The agent is actually more proactive than this — when a tool call fails with a 401 due to an expired session, the agent automatically starts a new OAuth flow and opens the browser. It doesn't just "prompt" the user. A more accurate description:

"If your session expires, the agent automatically detects it and initiates re-authentication by opening your browser."

6. Session duration

"Your overall session lasts approximately 30 days"

The default is exactly 30 days (720h), configurable via Helm values. "Approximately" is fine since it can vary by installation, but it may be worth noting it's the default.

Minor / Nice-to-have

• The first sentence of the doc ("Giant Swarm platform is ready to be used by AI agents, its integration lets you...") is a comma splice. Consider splitting into two sentences or using a semicolon.
• The troubleshooting example shows fernando@example.com — good use of a reserved domain.
• Consider adding a note about muster auth whoami as a quick way to verify identity.
• The Cursor config section says "restart the MCP server from Cursor's MCP panel" — it might help to mention that in Cursor you can also just toggle the server off/on from the MCP settings UI.

Overall

Solid first version. The main actionable items are fixing the context show command (will error as-is) and resolving the context/endpoint redundancy to avoid confusing the user. The rest are polish items.

[teemow]

Good first version of the muster docs -- well structured, helpful architecture diagram, and solid troubleshooting section. I've added inline suggestions that can be applied directly from the GitHub UI. The main issues are: a broken command (muster context show needs an argument), redundancy between context setup and --endpoint flag, and a few wording fixes for accuracy.

[teemow]

This context setup is great, but it becomes redundant because Step 4 passes --endpoint=... explicitly in the IDE config, which overrides the context.

The muster agent resolves endpoints with this precedence:

1. --endpoint flag (highest)
2. --context flag
3. MUSTER_CONTEXT env var
4. current-context from contexts.yaml

I'd suggest picking one approach:

• Option A: Keep context setup here, remove --endpoint from IDE configs in Step 4. The agent will resolve from the active context. This is cleaner for users with multiple installations.
• Option B: Remove Steps 2-3, and just rely on --endpoint in the IDE config + muster auth login --endpoint <url>.

[pipo02mix]

But I think this shows users how contexts works an even if you add the context and login step 4 works. It maybe redundant but helps end user to understand how muster works under the hood, dont you think?

[teemow]

I don't think we should add --endpoint if we tell users to run muster context use before. This just confuses users. If you want to explain more then you can add some note like this:

With a context in muster you don't have to type --endpoint for every muster command.