From 19377ad487ab4f91e16cd937ee152f1823e3125a Mon Sep 17 00:00:00 2001
From: timmy <timmy@stackchain.ai>
Date: Tue, 4 Aug 2026 21:02:56 +0000
Subject: [PATCH] docs: add tested local quickstart for issue 24

---
 README.md            | 32 ++++++++++++++++++++++++++++++++
 requirements.txt     |  1 +
 tests/test_readme.py | 13 +++++++++++++
 3 files changed, 46 insertions(+)

diff --git a/README.md b/README.md
index ced268c..fc5cf57 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,38 @@
 
 Live AI-driven adaptive UI for the Stackchain AI Lab Gitea experience.
 
+## Local quickstart
+
+Python 3.11 or newer is recommended. Create an isolated environment and install
+the pinned dependencies:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+```
+
+Point the dashboard at the Gitea server root (without `/api/v1`) and provide a
+read-scoped access token, then start the API and bundled frontend:
+
+```bash
+export GITEA_URL='https://forge.example.com'
+export GITEA_TOKEN='<read-scoped-token>'
+uvicorn src.main:app --host 127.0.0.1 --port 8000
+```
+
+Open `http://127.0.0.1:8000/` for the dashboard. To verify the backend and its
+Gitea connection directly, request
+`http://127.0.0.1:8000/api/v1/context`; a successful response is JSON containing
+`user`, `repos`, `issues`, and `pull_requests`. Never commit the token or place
+it in a tracked configuration file.
+
+Run the test suite with:
+
+```bash
+python3 -m pytest tests/ -q
+```
+
 ## Autonomous release worker
 
 The deterministic issue-to-release engine lives at `src/release_engine.py`.
diff --git a/requirements.txt b/requirements.txt
index c7acbdc..35a6f1f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -2,3 +2,4 @@ fastapi==0.133.1
 httpx==0.28.1
 pydantic==2.13.4
 pytest==9.1.1
+uvicorn==0.41.0
diff --git a/tests/test_readme.py b/tests/test_readme.py
index c9cf911..f5b6914 100644
--- a/tests/test_readme.py
+++ b/tests/test_readme.py
@@ -2,6 +2,7 @@ from pathlib import Path
 
 
 README = Path(__file__).parents[1] / "README.md"
+REQUIREMENTS = Path(__file__).parents[1] / "requirements.txt"
 
 
 def test_release_worker_instructions_use_direct_agent_execution():
@@ -10,3 +11,15 @@ def test_release_worker_instructions_use_direct_agent_execution():
     assert "codex" not in text.lower()
     assert "RELEASE_AGENT_COMMAND=true" in text
     assert "--issue 19" in text
+
+
+def test_readme_documents_a_complete_local_quickstart():
+    text = README.read_text()
+
+    assert "python3 -m venv .venv" in text
+    assert "pip install -r requirements.txt" in text
+    assert "GITEA_URL" in text
+    assert "GITEA_TOKEN" in text
+    assert "uvicorn src.main:app" in text
+    assert "http://127.0.0.1:8000/api/v1/context" in text
+    assert "uvicorn==" in REQUIREMENTS.read_text()