docs: update for v0.2.3–v0.2.4 changes (#51)

- Security FAQ: document well-known URL auth confirmation prompt and
  command validation (from #45)
- Troubleshooting: add MCP server initialization failure section — init
  errors are now logged instead of silently swallowed (from #45)
- Telemetry: document flush retry and flush-before-exit behavior
  (from #45, #46)
- Getting started: mention postinstall welcome banner and upgrade
  changelog display (from #48)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: anandgupta42

docs/docs/configure/telemetry.md

@@ -36,6 +36,12 @@ We collect the following categories of events:
 
 Each event includes a timestamp, anonymous session ID, and the CLI version.
 
+## Delivery & Reliability
+
+Telemetry events are buffered in memory and flushed periodically. If a flush fails (e.g., due to a transient network error), events are re-added to the buffer for one retry. On process exit, the CLI performs a final flush to avoid losing events from the current session.
+
+No events are ever written to disk — if the process is killed before the final flush, buffered events are lost. This is by design to minimize on-disk footprint.
+
 ## Why We Collect Telemetry
 
 Telemetry helps us:

docs/docs/getting-started.md

@@ -20,6 +20,8 @@ Unlike general-purpose coding agents, altimate is built for data teams:
 npm install -g @altimateai/altimate-code
 ```
 
+After install, you'll see a welcome banner with quick-start commands. On upgrades, the banner also shows what changed since your previous version.
+
 ## First run
 
 ```bash

docs/docs/security-faq.md

@@ -126,6 +126,21 @@ Or via environment variable:
 export ALTIMATE_TELEMETRY_DISABLED=true
 ```
 
+## What happens when I authenticate via a well-known URL?
+
+When you run `altimate auth login <url>`, the CLI fetches `<url>/.well-known/altimate-code` to discover the server's auth command. Before executing anything:
+
+1. **Validation** — The auth command must be an array of strings. Malformed or unexpected types are rejected.
+2. **Confirmation prompt** — You are shown the exact command and must explicitly approve it before it runs.
+
+```
+$ altimate auth login https://mcp.example.com
+◆ The server requests to run: gcloud auth print-access-token. Allow?
+│ ● Yes / ○ No
+```
+
+This prevents a malicious server from silently executing arbitrary commands on your machine.
+
 ## Are MCP servers a security risk?
 
 MCP (Model Context Protocol) servers extend Altimate Code with additional tools. They run as local subprocesses or connect via SSE/HTTP. Security considerations:

docs/docs/troubleshooting.md

@@ -62,6 +62,23 @@ altimate --print-logs --log-level DEBUG
 4. For Snowflake: ensure the warehouse is not suspended
 5. For BigQuery: check that the service account has the required IAM roles
 
+### MCP Server Initialization Failures
+
+**Symptoms:** MCP tools missing or MCP server not available after startup.
+
+**Solutions:**
+
+1. Check the log files — MCP initialization errors are now logged with the server name and error message:
+   ```
+   WARN failed to initialize MCP server { key: "my-tools", error: "..." }
+   ```
+2. Verify the MCP server command is correct in your config
+3. Test the server manually:
+   ```bash
+   altimate mcp test my-tools
+   ```
+4. Check that required environment variables are set (e.g., API keys referenced in the MCP config)
+
 ### LSP Server Won't Start
 
 **Symptoms:** No diagnostics or completions for a language.