diff --git a/.cursor/rules/git-workflow.mdc b/.cursor/rules/git-workflow.mdc
new file mode 100644
index 0000000..8c31560
--- /dev/null
+++ b/.cursor/rules/git-workflow.mdc
@@ -0,0 +1,12 @@
+---
+description: Branch only for code; documentation commits on main
+alwaysApply: true
+---
+
+# Git workflow (Neon Sprawl)
+
+- **Documentation-only work** — Commit directly on **`main`**. This means Markdown (`.md`) under `docs/`, root and nested `README.md` files, `neon_sprawl_vision.plan.md`, and other prose docs. No feature branch required.
+
+- **Code or implementation changes** — Use a **branch** (e.g. `feature/…`, `fix/…`), then merge to `main` when ready. This includes application source (**C#**, **GDScript**), Godot scenes and project files, `docker-compose.yml`, `.csproj` / build config, CI workflows, **JSON/YAML game data** under `content/`, and JSON Schema when it ships with data pipelines—not standalone doc prose.
+
+When a change mixes documentation and code, treat it as a **code change** (use a branch).
diff --git a/README.md b/README.md
index 36bd669..7b38f4d 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,11 @@ Full rationale and constraints: [`docs/architecture/tech_stack.md`](docs/archite
 
 Epic-level breakdown: [`docs/decomposition/README.md`](docs/decomposition/README.md).
 
+## Git workflow
+
+- **Documentation** (Markdown under `docs/`, README files, `neon_sprawl_vision.plan.md`): work and commit **directly on `main`**.
+- **Code and implementation** (server/client source, Godot project, `content/` data, Docker/build/CI config): use a **branch**, then merge to `main` when ready. Mixed doc + code changes follow the branch rule.
+
 ## Repository layout (prototype scaffold)
 
 | Path | Purpose |