docs: add pre-commit setup to bootstrap and deduplicate contributing guides

AGENTS.md

@@ -22,13 +22,17 @@ Follow these instructions in addition to any higher-level system or tool rules.
 - **Preserve public behavior and CLI UX** — no breaking changes to APIs, CLI flags, or exit codes unless explicitly requested.
 - **Update or add tests/docs** when you change user-facing behavior.
 - **Commit messages** must follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitizen itself).
+- **Pull requests** must follow the [Pull Request Guidelines](docs/contributing/pull_request.md) and the template in `.github/pull_request_template.md`.
 
 ## Setup and Validation
 
+> Full contributor guidelines (prerequisites, workflow, PR process): [`docs/contributing/contributing.md`](docs/contributing/contributing.md).
+
 ### Bootstrap
 
 ```bash
 uv sync --frozen --group base --group test --group linters
+uv run poe setup-pre-commit   # install git hooks (uses prek, a pre-commit runner)
 ```
 
 ### Local commands
@@ -44,7 +48,7 @@ Always run at least `uv run ruff check --fix . && uv run ruff format .` before p
 ### CI pipeline
 
 - CI runs `poe ci` on a matrix of Python 3.10–3.14 × ubuntu/macos/windows.
-- Pre-commit hooks are defined in `.pre-commit-config.yaml` and run via `prek`.
+- Pre-commit hooks are defined in `.pre-commit-config.yaml` and run via [`prek`](https://github.com/j178/prek) (a `pre-commit` compatible runner).
 - The matrix is **fail-fast**: inspect the earliest failing job that completed; others are cancelled.
 
 ### Common CI failure patterns

docs/contributing/contributing_tldr.md

@@ -2,38 +2,29 @@
 
 Feel free to send a PR to update this file if you find anything useful. 🙇
 
-## Environment
+For prerequisites and initial setup, see [Contributing to Commitizen](contributing.md#prerequisites-setup).
 
-- Python `>=3.10`
-- [uv](https://docs.astral.sh/uv/getting-started/installation/) `>=0.9.0`
+## Command Cheat Sheet
 
-## Useful commands
-
-Please check the [pyproject.toml](https://github.com/commitizen-tools/commitizen/blob/master/pyproject.toml) for a comprehensive list of commands.
-
-### Code Changes
+See [pyproject.toml](https://github.com/commitizen-tools/commitizen/blob/master/pyproject.toml) for the full list of poe tasks.
 
 ```bash
-# Ensure you have the correct dependencies
-uv sync --dev --frozen
-
-# Make ruff happy
+# Format code (ruff check --fix + ruff format)
 uv run poe format
 
-# Check if ruff and mypy are happy
+# Lint (ruff check + mypy)
 uv run poe lint
 
-# Check if mypy is happy in python 3.10
-mypy --python-version 3.10
+# Check mypy against a specific Python version
+uv run mypy --python-version 3.10
 
-# Run tests in parallel.
-pytest -n auto # This may take a while.
-pytest -n auto <test_suite>
-```
+# Run tests in parallel (may take a while)
+uv run pytest -n auto
+uv run pytest -n auto <test_suite>
 
-### Documentation Changes
-
-```bash
-# Build the documentation locally and check for broken links
+# Build and preview docs locally
 uv run poe doc
+
+# Run everything (format + lint + check-commit + coverage)
+uv run poe all
 ```