diff --git a/.rules.md b/.rules.md
index b9b94911..8700bbe9 100644
--- a/.rules.md
+++ b/.rules.md
@@ -19,6 +19,8 @@ uv run poe type-check               # Run ty type checker
 uv run poe unit-tests               # Run unit tests
 uv run poe check-docstrings         # Verify async docstrings match sync
 uv run poe fix-docstrings           # Auto-fix async docstrings
+uv run poe generate-models          # Regenerate _models.py from live OpenAPI spec
+uv run poe generate-models-from-file <path>  # Regenerate from a local OpenAPI spec file
 
 # Run a single test
 uv run pytest tests/unit/test_file.py
@@ -71,7 +73,15 @@ Docstrings are written on sync clients and **automatically copied** to async cli
 
 ### Data Models
 
-`_models.py` is **auto-generated** from the OpenAPI spec using `datamodel-code-generator`. Do not edit manually; regenerate with `uv run poe generate-models`. Contains Pydantic v2 `BaseModel` classes for all API responses.
+`src/apify_client/_models.py` is **auto-generated** — do not edit it manually.
+
+- Generated by `datamodel-code-generator` from the OpenAPI spec at `https://docs.apify.com/api/openapi.json` (config in `pyproject.toml` under `[tool.datamodel-codegen]`, aliases in `datamodel_codegen_aliases.json`)
+- After generation, `scripts/postprocess_generated_models.py` is run to apply additional fixes
+- To regenerate locally:
+  - From the live published spec: `uv run poe generate-models`
+  - From a local spec file: `uv run poe generate-models-from-file path/to/openapi.json`
+- In CI, model regeneration is triggered automatically by the `apify/apify-docs` repo when its OpenAPI spec changes (workflow `manual_regenerate_models.yaml`). It downloads the pre-built `openapi-bundles` artifact from the apify-docs workflow run, opens a PR titled `[TODO]: update generated models from apify-docs PR #N`, assigns it to the docs PR author, and posts a cross-repo comment on the original apify-docs PR
+- Manual regeneration is also possible from the GitHub Actions UI (`Regenerate models` workflow)
 
 ## Code Conventions
 
@@ -80,7 +90,13 @@ Docstrings are written on sync clients and **automatically copied** to async cli
 - **Type checking**: ty (Astral's type checker)
 - **Docstrings**: Google style format, single backticks for inline code references (`` `ApifyClient` `` not ``` ``ApifyClient`` ```)
 - **Imports**: `from __future__ import annotations` used throughout
-- **Commits**: [Conventional Commits](https://www.conventionalcommits.org/) format (feat, fix, refactor, etc.)
+- **Commits**: [Conventional Commits](https://www.conventionalcommits.org/) format. Choose the type based on *what* changed, not just *why*:
+  - `feat:` / `fix:` / `perf:` / `refactor:` / `style:` — **source code only**; these trigger a release and appear in the changelog
+  - `test:` — test additions or changes (no release triggered)
+  - `docs:` — documentation changes; also triggers a doc release on master
+  - `ci:` — CI/workflow changes
+  - `chore:` — dependency bumps, tooling, generated files (e.g. model regeneration PRs), and other housekeeping
+  - `build:` — build system changes
 
 ## Testing