docs: add FAQ and Troubleshooting section to README

[meichuanyi]

Summary

This PR adds a comprehensive FAQ and Troubleshooting section to the README to help new users get started faster and solve common issues without needing to open issues.

Changes

• Added FAQ section covering common questions about:

  • What is Sim and what does it do
  • Free vs cloud-hosted usage
  • Supported AI models and providers

• Added Installation & Setup section with solutions for:

  • Self-hosting requirements (Docker and Manual methods)
  • Installation instructions (NPM and Docker Compose)
  • Local AI model support (Ollama/vLLM)
  • Copilot API key configuration

• Added Troubleshooting section with solutions for:

  • Port already in use errors
  • Docker containers not starting
  • Database connection errors
  • Workflow not executing
  • Copilot not working

• Included links to documentation, Discord community, and GitHub issues

Motivation

As an open-source AI agent platform with visual workflow building, Sim has unique setup requirements that may be unfamiliar to new users. Having a centralized FAQ/Troubleshooting section in the README helps:

1. Reduce repetitive questions in Discord and Issues
2. Help new users choose between self-hosted and cloud options
3. Provide quick solutions for common Docker and database setup problems
4. Improve overall developer experience with self-serve troubleshooting

Checklist

• Content is accurate and links are valid
• Formatting follows existing README style
• Troubleshooting suggestions point to official docs
• No code changes, documentation only

[vercel]

Someone is attempting to deploy a commit to the Sim Team on Vercel.

A member of the Team first needs to authorize it.

[cursor]

PR Summary

Low Risk
Documentation-only changes; risk is limited to potential confusion if any instructions/links are inaccurate or become outdated.

Overview
Adds a new FAQ section to README.md covering what Sim is, licensing/cloud vs self-hosted, and supported model providers.

Expands the README with installation/setup answers (requirements, npx simstudio and Docker Compose commands, local model notes, and Copilot API key configuration) plus a troubleshooting checklist for common Docker/DB/port/workflow issues and quick links for getting help.

^{Reviewed by Cursor Bugbot for commit f5eda6c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a FAQ and Troubleshooting section to README.md to help new users self-serve common setup questions. The content is generally accurate and well-structured, but the "How do I install Sim?" answer for npx simstudio omits the hard Docker requirement that is already called out in the existing Quickstart section, which could mislead users into attempting the install without Docker.

Confidence Score: 4/5

Safe to merge after fixing the missing Docker prerequisite note in the npx simstudio FAQ answer.

One P1 finding: the FAQ install answer for npx simstudio omits a hard Docker requirement already documented in the Quickstart, which will actively mislead users. All other content is accurate and well-structured.

README.md — specifically the 'How do I install Sim?' FAQ answer around line 196–201

Important Files Changed

Filename	Overview
README.md	Adds FAQ and Troubleshooting section; npx simstudio FAQ answer omits the Docker prerequisite that is already documented in the Quickstart

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[New User Reads README] --> B{Choose deployment}
    B -->|Cloud| C[sim.ai managed service]
    B -->|Self-hosted| D{Choose method}
    D -->|NPM Package| E[npx simstudio]
    D -->|Docker Compose| F[docker compose up]
    D -->|Manual| G[Bun + PostgreSQL + pgvector]
    E -->|Requires| H[Docker must be installed]
    F -->|Requires| H
    H --> I[App runs on localhost:3000]
    G --> I
    I --> J{Issue?}
    J -->|Port conflict| K[Change port / stop service]
    J -->|DB error| L[Check pgvector / connection string]
    J -->|Copilot| M[Set COPILOT_API_KEY in .env]
    J -->|Workflow issue| N[Check API keys / node connections]

Loading

_{Reviews (1): Last reviewed commit: "docs: add FAQ and Troubleshooting sectio..." | Re-trigger Greptile}

[greptile-apps]

Missing Docker prerequisite for npx simstudio

The FAQ answer for "How do I install Sim?" presents npx simstudio without noting that Docker must be installed and running — a hard requirement already called out in the existing Quickstart section (line 59: "Docker must be installed and running on your machine."). A user following only the FAQ could invoke npx simstudio, hit a cryptic Docker error, and have no idea why. The Docker Compose option also requires Docker, so the prerequisite applies to both paths shown here.

Suggested change

	A: Copilot is a Sim-managed service. Generate a Copilot API key at https://sim.ai → Settings → Copilot, then set `COPILOT_API_KEY` in your `.env` file.
	### Troubleshooting
	**Port already in use errors**
	- Default ports: 3000 (app), 3002 (sockets), 5432 (PostgreSQL)
	**Q: How do I install Sim?**
	A: The easiest way is using the NPM package (requires Docker to be installed and running):
	```bash
	npx simstudio