diff --git a/CLAUDE.md b/CLAUDE.md
index c630bd1..fc44a03 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -85,6 +85,38 @@ GET  /api/session/:id/export    Download session as Markdown
 - System messages from Codex/Kiro (AGENTS.md, permissions, exit) are filtered via `isSystemMessage()`
 - Cursor `<user_query>` wrappers are stripped in `loadCursorDetail()`
 
+## Git workflow
+
+**`main` branch is protected.** All changes go through feature branches + pull requests.
+
+```bash
+# 1. Create a feature branch
+git checkout -b feat/my-feature    # or fix/bug-name, chore/cleanup
+
+# 2. Make changes, commit
+git add <files> && git commit -m "feat: description"
+
+# 3. Push and create PR
+git push -u origin feat/my-feature
+gh pr create --title "feat: description" --body "..."
+
+# 4. After review/approval, merge via GitHub
+gh pr merge <number> --squash
+```
+
+**Branch naming:**
+- `feat/` — new features
+- `fix/` — bug fixes
+- `chore/` — refactoring, docs, CI
+- `release/` — version bumps + publish
+
+**Commit messages:** Use conventional format: `feat:`, `fix:`, `chore:`, `docs:`, `perf:`.
+
+**PR rules:**
+- 1 approval required to merge into main
+- Keep PRs small and focused — one feature/fix per PR
+- Large PRs touching 5+ files should be split
+
 ## Versioning rules
 
 **IMPORTANT: Do not bump versions aggressively.**
@@ -100,11 +132,12 @@ Before bumping minor/major, ask: "Does this really warrant a version bump, or ca
 ## Publishing
 
 ```bash
-# Bump version in package.json, then:
-git add -A && git commit && git push && npm publish --access public
-
-# Also sync to ~/codedash:
-cp -r src/* ~/codedash/src/ && cp bin/cli.js ~/codedash/bin/ && cp package.json ~/codedash/
+# From a release branch:
+git checkout -b release/6.x.x
+# Bump version in package.json, commit, push, create PR
+# After merge to main:
+git checkout main && git pull
+npm publish --access public
 ```
 
 Package name: `codedash-app`, binary name: `codedash`
diff --git a/README.md b/README.md
index 91e8ce1..2956888 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,23 @@ curl -fsSL https://opencode.ai/install | bash            # OpenCode
 - At least one AI coding agent installed
 - macOS / Linux / Windows
 
+## Contributing
+
+`main` is protected. All changes go through feature branches and pull requests.
+
+```bash
+git checkout -b fix/my-fix
+# make changes
+git push -u origin fix/my-fix
+gh pr create
+```
+
+- **Branch naming:** `feat/`, `fix/`, `chore/`, `release/`
+- **1 approval** required to merge
+- Keep PRs small and focused
+
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for codebase details.
+
 ## License
 
 MIT
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index af44398..1343794 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -323,3 +323,29 @@ GET  /api/version               Current + latest npm version
 GET  /api/changelog             Changelog entries
 GET  /api/terminals             Available terminal apps
 ```
+
+---
+
+## Contributing
+
+### Git Workflow
+
+`main` is protected. All changes require a pull request with 1 approval.
+
+```
+main (protected)
+  ├── feat/session-titles    → PR → merge
+  ├── fix/cursor-path        → PR → merge
+  └── release/6.4.0          → PR → merge + npm publish
+```
+
+**Branch naming:** `feat/`, `fix/`, `chore/`, `release/`
+
+**Commit format:** Conventional — `feat:`, `fix:`, `chore:`, `docs:`, `perf:`
+
+### PR Guidelines
+
+- One feature or fix per PR
+- Keep PRs under 5 files when possible
+- Large features should be split into incremental PRs
+- Test locally with `node -e "require('./src/server')"` before pushing