Fix the smallest broken layer first.
Do not guess. Check Spark Live, then providers, then Telegram, then memory, then Spawner. Each command should make the next step obvious.
First five checks.
spark live status spark status spark providers status spark providers test --role chat spark verify --onboarding
If a Telegram error says a local service is unreachable, run /diagnose in Telegram or spark fix spawner locally.
Symptom to fix map.
Bot is quiet
Run spark fix telegram. Then check spark logs spark-telegram-bot --lines 80.
Bot says private or admin only
Send /myid, add that ID in spark setup, then restart Spark Live.
LLM replies fail
Run spark providers test --role chat. Rerun setup if the selected provider is missing or pointing to the wrong endpoint.
Hosted provider fails
Installed is not authenticated. Codex needs a hosted OPENAI_API_KEY; Claude needs ANTHROPIC_API_KEY; local models need reachable endpoints.
Memory does not stick
Run spark verify --deep. Then test /remember and /recall with a unique phrase.
Spawner is unreachable
Run spark fix spawner, then spark live status. The user-friendly error is "Mission Control is offline."
Update failed
Run spark security audit and spark logs. If a trust scan blocks a test fixture, update Spark before bypassing anything.
Hosted Railway provider checks.
On Railway, provider binaries and provider auth are separate checks. A container can have codex or claude on PATH and still fail until the service has valid hosted credentials.
For service layout, private DNS, relay keys, and smoke tests, use the Railway/VPS operations page.
Codex
Use a dedicated OPENAI_API_KEY and persistent CODEX_HOME. Do not copy a personal desktop Codex OAuth session into Railway.
Claude
Use ANTHROPIC_API_KEY for hosted Claude. Claude Code OAuth is a local desktop route.
Local models
Use Ollama, LM Studio, vLLM, TGI, or llama.cpp as reachable endpoints. Railway should not download large models into the app container.
spark providers status spark providers test --role mission spark verify --hosted --deep
When to use LLM Doctor.
Use the LLM doctor after the basic checks show a real problem and the normal fix command did not solve it.
spark doctor llm "Telegram bot is quiet after restart" --save-report spark doctor llm "Spawner says ECONNREFUSED on 5173" --include-logs --save-report
Privacy rule
Doctor redacts secrets before sending context to the user's configured LLM. Logs are excluded unless the user opts in.