diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..ece4af3
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,175 @@
+# Scripts Directory
+
+Utility scripts for development, testing, and maintenance.
+
+## Available Scripts
+
+### 🔍 `lint.sh`
+Unified linting for all project code (Python + TypeScript/Svelte).
+
+```bash
+./scripts/lint.sh
+```
+
+**What it checks:**
+- Backend: Ruff (check + format)
+- Frontend: ESLint, Prettier, TypeScript
+
+**Auto-enters nix shell if needed**
+
+---
+
+### 🔧 `install-hooks.sh`
+Install git hooks for automatic code quality checks.
+
+```bash
+./scripts/install-hooks.sh
+```
+
+**Installs:**
+- `pre-commit` - Runs linting before each commit
+- `pre-push` - Runs tests before push
+
+**Skip hooks:** `git commit --no-verify`
+
+---
+
+### 🧪 `test-auth.sh`
+Automated testing for Phase 3 authentication system.
+
+```bash
+./scripts/test-auth.sh
+```
+
+**Tests:**
+- Health check
+- User registration
+- User login
+- Protected endpoints
+- Token validation
+- Password validation
+- Error handling
+
+**Requires:** Backend server running on localhost:8000
+
+---
+
+### 🚀 `quick-start.sh`
+Automated setup for first-time development.
+
+```bash
+./scripts/quick-start.sh
+```
+
+**Does:**
+- Creates `.env` files
+- Creates database
+- Runs migrations
+- Shows next steps
+
+---
+
+## Nix Flake Apps
+
+You can also use nix apps for consistent environment:
+
+```bash
+# Lint all code
+nix run .#lint
+
+# Auto-fix linting issues
+nix run .#lint-fix
+```
+
+## Git Hooks
+
+After running `./scripts/install-hooks.sh`:
+
+**Pre-commit hook:**
+- Automatically runs on `git commit`
+- Checks Python (ruff) and TypeScript (ESLint/Prettier)
+- Prevents commits with linting errors
+- Skip with: `git commit --no-verify`
+
+**Pre-push hook:**
+- Automatically runs on `git push`
+- Runs full test suite (backend + frontend)
+- Prevents pushes with failing tests
+- Skip with: `git push --no-verify`
+
+## Development Workflow
+
+### Daily Development
+```bash
+# 1. Make changes to code
+# 2. Lint runs automatically on commit
+git add .
+git commit -m "feat: my changes"  # Hooks run automatically
+
+# 3. If lint fails, auto-fix:
+nix run .#lint-fix
+# Then commit again
+```
+
+### Manual Checks
+```bash
+# Before committing, check manually:
+./scripts/lint.sh
+
+# Auto-fix issues:
+nix run .#lint-fix
+# OR
+cd backend && ruff format app/
+cd frontend && npx prettier --write src/
+```
+
+## Troubleshooting
+
+### "ruff: command not found"
+**Solution:** Run inside nix shell:
+```bash
+nix develop
+./scripts/lint.sh
+```
+
+Or the script will auto-enter nix shell for you.
+
+### "node_modules not found"
+**Solution:** Install frontend dependencies:
+```bash
+cd frontend
+npm install
+```
+
+### Git hooks not running
+**Solution:** Reinstall hooks:
+```bash
+./scripts/install-hooks.sh
+```
+
+### Want to disable hooks temporarily
+**Solution:** Use `--no-verify`:
+```bash
+git commit --no-verify
+git push --no-verify
+```
+
+## Adding New Linting Rules
+
+### Backend (Python)
+Edit `backend/pyproject.toml`:
+```toml
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "N", "UP", "B", "C4", "SIM"]
+ignore = ["B008", "N818"]  # Add more as needed
+```
+
+### Frontend (TypeScript)
+Edit `frontend/.eslintrc.cjs` and `frontend/.prettierrc`
+
+## CI/CD Integration
+
+The linting checks are also run in CI/CD (see `.gitea/workflows/ci.yml`).
+
+All code must pass linting before merging to main.
+