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`.

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

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()