diff --git a/README.md b/README.md
index 6c6ca9e..4110cea 100644
--- a/README.md
+++ b/README.md
@@ -181,6 +181,9 @@ ollama pull mistral
 issuesheriff setup   # enter "mistral" when asked for Ollama model
 ```
 
+For full step-by-step local setup (install, pull model, configure, run), see
+[`docs/ollama.md`](docs/ollama.md).
+
 ### <img src="assets/icons/bolt.svg" width="14" height="14"> No AI — zero config
 
 Heuristic classification + TF-IDF duplicate detection, no API needed:
diff --git a/docs/ollama.md b/docs/ollama.md
new file mode 100644
index 0000000..44f6bb8
--- /dev/null
+++ b/docs/ollama.md
@@ -0,0 +1,76 @@
+# Ollama setup for IssueSheriff
+
+This project can run without external API keys using Ollama for local embeddings and
+classification flow.
+
+## 1. Install Ollama
+
+1. Download Ollama for your OS:
+   - macOS: `brew install ollama`
+   - Linux: follow the package instructions for your distro from <https://ollama.com/download>
+2. Verify the installation:
+
+   ```bash
+   ollama --version
+   ```
+
+3. Start the Ollama service if needed:
+
+   ```bash
+   ollama serve
+   ```
+
+## 2. Pull an example model
+
+IssueSheriff works well with smaller chat models for local setup.
+
+```bash
+ollama pull mistral
+```
+
+## 3. Configure IssueSheriff to use Ollama
+
+1. Run setup:
+
+   ```bash
+   issuesheriff setup
+   ```
+
+2. In the wizard, choose Ollama as backend and set the model to `mistral`
+   when prompted.
+3. Confirm values in `~/.config/issuesheriff/.env`:
+
+   ```bash
+   grep -E "^OLLAMA_MODEL|^OLLAMA_BASE_URL|^ISSUESHERIFF_AI_PROVIDER" ~/.config/issuesheriff/.env
+   ```
+
+   Typical values:
+
+   ```text
+   ISSUESHERIFF_AI_PROVIDER=ollama
+   OLLAMA_MODEL=mistral
+   OLLAMA_BASE_URL=http://localhost:11434
+   ```
+
+## 4. Run a quick local validation
+
+Analyze one issue payload to confirm the local AI path works:
+
+```bash
+cat <<'JSON' > /tmp/local-issue.json
+{
+  "title": "Issue with typo in command output",
+  "body": "The latest scan did not pick the right labels."
+}
+JSON
+
+issuesheriff analyze /tmp/local-issue.json --no-reply
+```
+
+If you want a GitHub-driven flow with local Ollama, run:
+
+```bash
+issuesheriff setup   # ensure OLLAMA_MODEL is set
+issuesheriff scan microsoft/vscode --limit 3
+```
+