mockstack 0.12.1__tar.gz → 0.14.0__tar.gz

mockstack-0.14.0/.env.example

@@ -0,0 +1,49 @@
+# Example environment variables for mockstack.
+# Copy this file to `.env` in the directory you run mockstack from and adjust the values.
+# Every setting, with its default, is listed at https://promptromp.github.io/mockstack/configuration/
+
+# the strategy to use: filefixtures (the default) or proxyrules
+MOCKSTACK__STRATEGY = filefixtures
+
+# strategy-specific settings
+
+# base dir for all templates. Required by the 'filefixtures' strategy
+# (and other hybrid strategies utilizing templates); the directory must exist.
+MOCKSTACK__TEMPLATES_DIR = "/some/path/templates/"
+
+# When using filefixtures strategy, controls whether POST requests first try a
+# matching template (default: true). With templates off, or when no template
+# matches, a POST is handled as a search, a command or a simulated create.
+MOCKSTACK__FILEFIXTURES_ENABLE_TEMPLATES_FOR_POST = false
+
+# When using filefixtures strategy, controls whether a POST with no matching template
+# simulates creating the resource (default: true) or gets the same 404 as a GET.
+MOCKSTACK__FILEFIXTURES_SIMULATE_CREATE_ON_MISSING = true
+
+# rules file for the proxyrules strategy. Required by the 'proxyrules' strategy; the
+# file must exist. See examples/proxyrules-with-rules-file/ and
+# mockstack/tests/fixtures/proxyrules.yml for examples.
+MOCKSTACK__PROXYRULES_RULES_FILENAME="/some/path/proxyrules.yml"
+
+# reverse_proxy (default), http_307_temporary or http_301_permanent
+MOCKSTACK__PROXYRULES_REDIRECT_VIA = reverse_proxy
+# timeout in seconds for reverse-proxied requests (default: 10.0)
+MOCKSTACK__PROXYRULES_REVERSE_PROXY_TIMEOUT = 10.0
+MOCKSTACK__PROXYRULES_SIMULATE_CREATE_ON_MISSING = true
+MOCKSTACK__PROXYRULES_VERIFY_SSL_CERTIFICATES = true
+
+# record mode for the proxyrules strategy: off (default), missing or overwrite.
+# missing records a fixture rule's file from the next matching URL rule when the file
+# does not exist yet; overwrite also re-records files recorded before. Requests really
+# reach the upstream until recorded. Never enable on a shared or exposed instance.
+# See https://promptromp.github.io/mockstack/strategies/proxyrules/#recording-fixtures
+MOCKSTACK__PROXYRULES_RECORD_MODE = off
+# directory every recorded fixture must resolve inside; required when recording.
+# MOCKSTACK__PROXYRULES_RECORD_ROOT = "/some/path/fixtures/"
+# optional module:function called on every body before it is recorded (must be importable).
+# MOCKSTACK__PROXYRULES_RECORD_SCRUBBER = "my_scrubbers:mask_emails"
+
+# OpenTelemetry settings
+MOCKSTACK__OPENTELEMETRY__ENABLED = true
+MOCKSTACK__OPENTELEMETRY__ENDPOINT = "http://localhost:4317/"
+MOCKSTACK__OPENTELEMETRY__CAPTURE_RESPONSE_BODY = true

{mockstack-0.12.1 → mockstack-0.14.0}/.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v6
@@ -32,16 +32,36 @@ jobs:
     - name: Install ruff
       uses: astral-sh/ruff-action@v4.0.0
       with:
-        version: "latest"
+        # Pinned to the ruff-pre-commit rev: new ruff releases add rules to the selected
+        # families, which should arrive through a deliberate bump, not a random CI run.
+        version: "0.16.7"
     - name: Install the project
       run: uv sync --all-extras --dev
     - name: Run ruff lint and formatting checks
       run: |
         ruff check
-        ruff format
+        ruff format --check
     - name: Run mypy
       run: |
         uv pip install types-pyyaml
         uv run mypy mockstack
     - name: Run tests
       run: uv run pytest
+    - name: Run live tests
+      run: uv run pytest -m slow mockstack/tests/live -v
+
+  docs:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Install uv and set the python version
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        python-version: "3.13"
+        version: "latest"
+    - name: Build docs strictly
+      run: |
+        cp README.md docs/
+        uvx --with mkdocs-material mkdocs build --strict

{mockstack-0.12.1 → mockstack-0.14.0}/.github/workflows/smoke-test-pypi.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.13", "3.14"]
     steps:
       - name: Install uv with Python ${{ matrix.python-version }}
         uses: astral-sh/setup-uv@v8.1.0

{mockstack-0.12.1 → mockstack-0.14.0}/.gitignore

@@ -173,3 +173,7 @@ cython_debug/
 
 # do not check in any user templates
 templates/*.j2
+
+# rules files rendered from the examples' ${VAR} placeholders
+examples/**/rules.local.yml
+examples/proxyrules-cookbook/09-recording/fixtures/

{mockstack-0.12.1 → mockstack-0.14.0}/.pre-commit-config.yaml

@@ -1,4 +1,6 @@
 fail_fast: true
+default_language_version:
+  python: python3
 repos:
 -   repo: local
     hooks:
@@ -10,7 +12,7 @@ repos:
         language: pygrep
         types: [text]
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v5.0.0
+  rev: v6.0.0
   hooks:
     - id: check-added-large-files
     - id: fix-byte-order-marker
@@ -24,23 +26,27 @@ repos:
     - id: end-of-file-fixer
     - id: trailing-whitespace
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.11.9
+  rev: v0.16.7
   hooks:
     # Run the linter.
     - id: ruff
       args: [ --fix ]
     # Run the formatter.
     - id: ruff-format
-- repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.15.0
-  hooks:
-    - id: mypy
-      additional_dependencies: [types-pyyaml>=6.0.12]
 - repo: local
   hooks:
+  # mypy runs from the dev dependency group in uv.lock, exactly as CI runs it: the
+  # stricter checks need the real third-party packages installed, which an isolated
+  # hook environment would have to duplicate in `additional_dependencies`.
+  - id: mypy
+    name: mypy
+    entry: bash -ec "uv run mypy mockstack"
+    language: system
+    types: [python]
+    pass_filenames: false
   - id: pytest
     name: pytest [with coverage, without slow]
-    entry: bash -ec "uv run python -m pytest --cov=mockstack mockstack/tests --cov-fail-under='85' -m 'not slow'"
+    entry: bash -ec "uv run python -m pytest --cov=mockstack mockstack/tests --cov-fail-under='90' -m 'not slow'"
     language: system
     types: [python]
     pass_filenames: false

mockstack-0.14.0/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+Guidance for AI coding agents and contributors working in this repository.
+
+## What mockstack is
+
+mockstack is an API-mocking service built on FastAPI. A catch-all route hands every
+request to one *strategy*, selected with the `strategy` setting:
+
+- `filefixtures`: renders Jinja templates from `templates_dir`, chosen from the request
+  path, and simulates resource creation, searches and commands for POSTs.
+- `proxyrules`: evaluates an ordered YAML rules file. The first matching rule serves a
+  `file:///` fixture (with the rule's optional `status` and `response_headers`),
+  reverse-proxies to a real service, or redirects. In record mode
+  (`proxyrules_record_mode`) a missing fixture is recorded from the next matching URL
+  rule. Rules match on path, method and `headers`/`query`/`body`/`json` predicates, and
+  every response is stamped with `X-Mockstack-Result` and `X-Mockstack-Rule`.
+
+Both share `CreateMixin` for simulated creates. Settings come from pydantic-settings:
+CLI flags, `MOCKSTACK__*` environment variables, or a `.env` file.
+
+## Layout
+
+- `mockstack/main.py`: app factory (`create_app`) and the `mockstack` CLI entry point
+- `mockstack/config.py`: `Settings`; `mockstack/constants.py`: enums, header names
+- `mockstack/strategies/`: `base.py`, `filefixtures.py`, `proxyrules.py`,
+  `create_mixin.py`, `factory.py`
+- `mockstack/rules.py`: the proxyrules `Rule`: predicates, load-time validation,
+  template context
+- `mockstack/recording.py`: record-mode building blocks: fixture encoding that renders
+  back to the exact body, the recorded marker, root confinement and atomic writes
+- `mockstack/templating.py`: Jinja environment and path-to-template-name resolution
+- `mockstack/intent.py`, `mockstack/identifiers.py`: POST intent (search, command,
+  create) and path-identifier heuristics
+- `mockstack/routers/`: catch-all and homepage routes
+- `mockstack/tests/`: unit tests; `conftest.py` holds fixtures shared by unit and live
+  tests (`make_settings`, `make_request`, `write_rules`, `write_template`, `span`), and
+  `strategies/conftest.py` adds strategy helpers (`traced_request`,
+  `proxyrules_strategy`, `apply_rule`, `upstream_send`, `span_attributes`). Build settings with
+  `make_settings`: it ignores
+  `MOCKSTACK__*` environment variables and `.env` files
+- `mockstack/tests/live/`: live tests against real uvicorn servers on loopback sockets;
+  `conftest.py` provides the session-scoped recording echo `upstream`, the module-scoped
+  `mockstack_server`, `proxyrules_settings` and `render_rules`; `test_record_mode_live.py`
+  records into temporary directories, never the repository
+- `examples/`: runnable examples; `examples/proxyrules-cookbook/` holds the files
+  embedded in the cookbook docs page
+- `docs/`: the MkDocs Material site (`mkdocs.yml`); the home page is `README.md`
+
+## Commands
+
+```bash
+uv sync                                         # install
+uv run pytest -q --cov=mockstack                # unit tests; live tests are deselected
+uv run pytest -m slow mockstack/tests/live -v   # live socket tests
+uv run mypy mockstack
+uvx ruff check && uvx ruff format --check
+cp README.md docs/ && uvx --with mkdocs-material mkdocs build --strict
+uvx pre-commit run --all-files                  # ruff, mypy, unit tests with coverage >= 90%
+```
+
+mockstack requires Python 3.13 or later; CI tests 3.13 and 3.14. Ruff (line length 120)
+and mypy are configured in `pyproject.toml`: production code must be fully annotated,
+and a `# noqa` names its rule code with the reason on the line above. CI and pre-commit
+pin ruff (0.16.7); if a newer `uvx ruff` reports findings they do not, run
+`uvx ruff@0.16.7`. Coverage measures production code only, and the pre-commit pytest
+hook fails below 90%.
+
+If `VIRTUAL_ENV` points at another checkout, `unset VIRTUAL_ENV` first so `uv` uses
+this project's `.venv`.
+
+The docs build copies `README.md` to `docs/README.md` as the site's home page. That
+copy is a build artifact and is gitignored: never commit it. The build is strict and
+`pymdownx.snippets` has `check_paths: true`, so a broken link or a missing embedded
+file fails it. CI runs the unit tests, the live tests, mypy, ruff and the docs build.
+
+## Conventions
+
+- **TDD.** Write the failing test first. Unit-test logic; add a live test when the
+  behaviour depends on real sockets, HTTP framing or a real upstream.
+- **Live tests are marked `slow`** (`pytestmark = pytest.mark.slow`). `pyproject.toml`
+  deselects them by default, so run them explicitly.
+- **Docs examples must be backed by tests.** Cookbook recipes are real files under
+  `examples/proxyrules-cookbook/`, embedded in `docs/guides/proxyrules-cookbook.md` with
+  `--8<--`. `mockstack/tests/live/test_cookbook.py` runs every `curl` command on that
+  page, and checks the page embeds every recipe file and that the README's
+  proxyrules example matches recipe 1. Change a recipe's files, page section and test
+  together. `mockstack/tests/test_docs_yaml.py` checks that every YAML block in the
+  docs parses, and `test_docs_settings.py` that every `MOCKSTACK__*` variable in the
+  docs, examples and `.env.example` files names a real setting.
+- **Regexes in YAML** go in plain or single-quoted scalars: a double-quoted `"\1"`
+  does not parse.
+- **Fail at load, not per request.** Rules are validated and compiled when the
+  strategy is constructed. Every `proxyrules` response, including errors, carries the
+  result headers.
+- **Keep names generic** in code, tests, docs and examples: projects service,
+  analytics SQL gateway, `sales_facts`, orders, users. Never use company, product or
+  internal service names.
+- **Branches.** Pushes to `main` and to any `docs/**` branch deploy the docs site
+  (`.github/workflows/publish-docs.yml`), so never push a `docs/...` branch casually.
+  Use `feat/`, `fix/` and similar prefixes for working branches.
+- **Commits.** Conventional prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`,
+  `ci:`). Stage files by explicit path. Commit trailers are added by the tool, so do
+  not type them by hand.

{mockstack-0.12.1 → mockstack-0.14.0}/CONTRIBUTING.md

@@ -6,7 +6,8 @@ Thank you for your interest in contributing to mockstack! We welcome contributio
 
 ### Prerequisites
 
-- Python 3.11 or higher
+- Python 3.13 or higher (CI tests 3.13 and 3.14)
+- [uv](https://docs.astral.sh/uv/)
 - Git
 - A GitHub account
 
@@ -18,15 +19,16 @@ Thank you for your interest in contributing to mockstack! We welcome contributio
    git clone https://github.com/YOUR_USERNAME/mockstack.git
    cd mockstack
    ```
-3. Create a virtual environment:
+3. Install the package in development mode, with its development dependencies. `uv sync`
+   creates the `.venv` virtual environment itself:
    ```bash
-   uv venv
-   source .venv/bin/activate  # On Windows: venv\Scripts\activate
+   uv sync
    ```
-4. Install the package in development mode:
+   Run commands in it with `uv run` (e.g. `uv run pytest`), or activate it with
+   `source .venv/bin/activate` (on Windows: `.venv\Scripts\activate`).
+4. Install the pre-commit hooks, which run ruff, mypy and the unit tests on every commit:
    ```bash
-   uv sync
-   pip install -e .
+   uvx pre-commit install
    ```
 
 ## How to Contribute
@@ -38,7 +40,7 @@ If you find a bug, please create an issue using our **Bug Report** template. Thi
 - A clear description of the problem
 - Steps to reproduce the issue
 - Expected vs actual behavior
-- Your environment details (Python version, pytest version, etc.)
+- Your environment details (mockstack version, Python version, OS, etc.)
 - Any relevant code snippets or error messages
 
 ### Suggesting Features
@@ -70,7 +72,9 @@ We welcome feature suggestions! Please use our **Feature Request** template when
 
 4. **Run the test suite**:
    ```bash
-   pytest
+   uv run pytest                               # unit tests
+   uv run pytest -m slow mockstack/tests/live  # live tests against real servers on loopback sockets
+   uvx pre-commit run --all-files              # ruff, mypy, and the unit tests with a 90% coverage threshold
    ```
 
 5. **Commit your changes**:
@@ -91,11 +95,11 @@ We welcome feature suggestions! Please use our **Feature Request** template when
 
 ### Code Style
 
-- Follow PEP 8 Python style guidelines. We use `ruff` for linting and formatting.
+- Follow PEP 8 Python style guidelines. We use `ruff` for linting and formatting, with the rule families configured in `pyproject.toml` (bugbear, bandit, pyupgrade, simplify and more). CI and the pre-commit hooks pin the ruff version.
 - Use meaningful variable and function names
-- Write clear commit messages
-- Keep line length reasonable (ideally under 120 characters)
-- Use type hints where appropriate
+- Write clear commit messages, with a conventional prefix (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `ci:`)
+- Keep lines within 120 characters (enforced by `ruff`)
+- Fully annotate production code: mypy runs with `disallow_untyped_defs`. Tests may leave fixture and parametrized arguments unannotated
 
 ### Testing
 

{mockstack-0.12.1 → mockstack-0.14.0}/Dockerfile

@@ -2,7 +2,7 @@
 
 # Define build argument for version
 ARG PYTHON_IMAGE_VERSION=3.13-slim
-ARG MOCKSTACK_VERSION=0.8.0
+ARG MOCKSTACK_VERSION=0.14.0
 
 # ---------------------------- Base Image --------------------------------
 

{mockstack-0.12.1/mockstack.egg-info → mockstack-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.12.1
+Version: 0.14.0
 Summary: An API mocking workhorse
 Author-email: Adam Ever-Hadani <mockstack.contact@gmail.com>
 License-Expression: MIT
@@ -9,26 +9,27 @@ Project-URL: Issues, https://github.com/promptromp/mockstack/issues
 Keywords: mocking,integration-testing,testing,microservices,api
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colorama>=0.4.6
-Requires-Dist: fastapi[standard]>=0.115.12
+Requires-Dist: fastapi[standard]>=0.141.1
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.1.6
-Requires-Dist: opentelemetry-distro[otlp]>=0.53b1
-Requires-Dist: opentelemetry-instrumentation-fastapi>=0.53b1
-Requires-Dist: pydantic>=2.11.3
-Requires-Dist: pydantic-settings>=2.9.1
-Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: rich>=14.0.0
-Requires-Dist: typer>=0.15.2
-Requires-Dist: uvicorn>=0.34.2
+Requires-Dist: opentelemetry-distro[otlp]>=0.65b0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.2
+Requires-Dist: uvicorn>=0.53.0
 Provides-Extra: llm
-Requires-Dist: ollama>=0.4.8; extra == "llm"
+Requires-Dist: ollama>=0.6.2; extra == "llm"
 Dynamic: license-file
 
 ![mockstack logo](https://github.com/promptromp/mockstack/raw/main/docs/assets/mockstack.png)
@@ -59,6 +60,11 @@ Use mockstack for:
 Highlights include:
 
 * Multiple strategies for handling requests such as [Jinja](https://jinja.palletsprojects.com/en/stable/) template files with intelligent URL request-to-template routing, proxy strategy, and mixed strategies. :game_die:
+* Rule predicates for the `proxyrules` strategy: match requests on path, method, headers, query parameters and JSON body fields, then serve a fixture, reverse-proxy to a real service, or redirect. :dart:
+* Dynamic replacements: a rule's replacement can be a Jinja template, so a request header can pick the fixture scenario to serve. :twisted_rightwards_arrows:
+* Result headers: every `proxyrules` response is stamped with `X-Mockstack-Result` and `X-Mockstack-Rule`, so a test can assert it got a fixture and not the real service. :label:
+* Fixture status codes and headers: a `proxyrules` fixture can answer with any status and extra headers, e.g. a 503 with `Retry-After`, to test how a client handles a failing dependency. :vertical_traffic_light:
+* Record mode: `proxyrules` can record real responses into the fixtures its rules serve, with an optional scrubber, then replay them without the real service. :red_circle:
 * Observability via [OpenTelemetry](https://opentelemetry.io/) integration. Get detailed traces of your sessions instantly reported to backends such as [Grafana](https://grafana.com/), [Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), etc. :eyes:
 * Configurability via [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) supports customizing behaviour via environment variables and a `.env` file. :flags:
 * Comprehensive unit-tests, linting and formatting coverage as well as vulnerabilities and security scanning with full CI automation to ensure stability and a high-quality codebase for production-grade use. :+1:
@@ -74,12 +80,13 @@ or install into a persistent environment and add it to the PATH with:
 
     uv tool install mockstack
 
+mockstack requires Python 3.13 or later; `uvx` and `uv tool install` pick a compatible interpreter, downloading one if needed.
 
 ## Usage
 
 See the [examples](https://github.com/promptromp/mockstack/blob/main/examples/) directory for complete examples with documentation.
 
-Available configuration options are [here](https://github.com/promptromp/mockstack/blob/main/mockstack/config.py).
+Available configuration options are described in the [Configuration](https://promptromp.github.io/mockstack/configuration/) reference, and defined [here](https://github.com/promptromp/mockstack/blob/main/mockstack/config.py).
 
 Setting individual options can be done either through an `.env` file, individual environment variables, or command-line arguments.
 
@@ -103,37 +110,84 @@ See also the included [.env.example](https://github.com/promptromp/mockstack/blo
 Out of the box, you get the following behavior when using the default `filefixtures` strategy:
 
 - The HTTP request `GET /someservice/api/v1/user/c27f5b2b-6e81-420d-a4e4-6426e1c32db8` will try to find `<templates_dir>/someservice-api-v1-user.c27f5b2b-6e81-420d-a4e4-6426e1c32db8.j2`,
-  and will fallback to `<templates_dir>/someservice-api-v1-user.j2` (and finally to `index.j2` if exists). These are j2 files that have access to request body context variables.
-- The HTTP request `POST /someservice/api/v2/item` with a JSON body will attempt to intelligently simulate the creation of a resource, returning the appropriate status code and will echo back the provided request resource, after injecting additional metadata fields based on strategy configuration. This is useful for services that expect fields such as `id` and `created_at` on returned created resources.
-- HTTP requests for `DELETE` / `PUT` / `PATCH` are a no-op by default, simply returning the appropriate status code.
-- The HTTP request `POST /someservice/api/v2/embedding_search` will be handled as a search request rather than a resource creation, returning an appropriate http status code and mock results based on user-configurable formatting.
+  and will fallback to `<templates_dir>/someservice-api-v1-user.j2` (and finally to `index.j2` if exists). These are j2 files that have access to request context variables (query parameters, headers, the JSON body and the identifiers in the path).
+- The HTTP request `POST /someservice/api/v2/item` with a JSON body will attempt to intelligently simulate the creation of a resource, returning the appropriate status code and will echo back the provided request resource, after injecting additional metadata fields based on strategy configuration. This is useful for services that expect fields such as `id` and `created_at` on returned created resources. Templates are tried first, so a template matching the path (`index.j2` included) answers the POST instead, unless `filefixtures_enable_templates_for_post=false`. This fallback can be turned off with `filefixtures_simulate_create_on_missing=false`, in which case a create-looking POST with no matching template gets a 404 instead.
+- HTTP requests for `DELETE` / `PUT` / `PATCH` are a no-op by default, simply returning the appropriate status code (204). `HEAD` and `OPTIONS` requests are answered 405.
+- The HTTP request `POST /someservice/api/v2/embedding_search` will be handled as a search request rather than a resource creation: it is answered from its template (`someservice-api-v2-embedding_search.j2`), or with a 404 when there is none.
 
 Overall, the design philosophy is that things "just work". The framework attempts to intelligently deduce the intent of the request as much as possible and act accordingly,
 while leaving room for advanced users to go in and customize behavior using the configuration options.
 
+### Mix fixtures and real services
+
+With the `proxyrules` strategy, one mockstack instance can serve fixtures to test traffic and pass everything else through to the real service. Rules are tried in order and the first match wins:
+
+```yaml
+rules:
+  - name: projects-fixture
+    method: GET
+    pattern: ^/projects/api/v1/project/(?P<id>[a-z0-9-]+)$
+    headers:
+      x-test-run: ".+"
+    replacement: file://${FIXTURES_DIR}/projects/project.json.j2
+
+  - name: projects-passthrough
+    pattern: ^/projects/(.*)
+    replacement: ${UPSTREAM_URL}/\1
+```
+
+Fill in the `${FIXTURES_DIR}` and `${UPSTREAM_URL}` placeholders (for example with `envsubst`), then start mockstack with `MOCKSTACK__STRATEGY=proxyrules` and `MOCKSTACK__PROXYRULES_RULES_FILENAME` pointing at the result. A request tagged with `X-Test-Run` is served from the fixture (`X-Mockstack-Result: template`); the untagged one is reverse-proxied to the real service (`X-Mockstack-Result: proxy`):
+
+```shell
+curl -i -H "X-Test-Run: ci-42" http://127.0.0.1:8000/projects/api/v1/project/proj-123
+curl -i http://127.0.0.1:8000/projects/api/v1/project/proj-123
+```
+
+The [ProxyRules cookbook](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/) walks through this recipe and more (per-scenario fixtures, matching on request bodies and query parameters, asserting in tests, error responses, recording fixtures), each backed by a live test.
+
+### Record fixtures from a real service
+
+Instead of writing fixtures by hand, record them: with record mode on, a fixture rule whose file does not exist yet sends the request on to the next matching URL rule, saves the response into the fixture file, and serves it from there. Later requests are replayed from the file without calling the service. Record mode is off by default:
+
+```shell
+MOCKSTACK__STRATEGY=proxyrules MOCKSTACK__PROXYRULES_RULES_FILENAME=rules.yml \
+  MOCKSTACK__PROXYRULES_RECORD_MODE=missing MOCKSTACK__PROXYRULES_RECORD_ROOT=fixtures \
+  uv run mockstack
+```
+
+Requests really reach the service until their response is recorded, so record against a safe environment and review the recorded files before committing them. An optional scrubber can mask sensitive data first; see [Recording fixtures](https://promptromp.github.io/mockstack/strategies/proxyrules/#recording-fixtures) and the cookbook's [Record fixtures from a real service](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/#9-record-fixtures-from-a-real-service).
 
 ## Testing
 
 Invoke unit-tests with:
 
-    uv run python -m pytest
+    uv run pytest
 
-Linting, formatting, static type checks etc. are all managed via [pre-commit](https://pre-commit.com/) hooks. These will run automatically on every commit. You can invoke these manually on all files with:
+Live tests start real mockstack and upstream servers on loopback sockets, including one that runs every example on the ProxyRules cookbook page. They are marked `slow` and deselected by default; run them with:
 
-    pre-commit run --all-files
+    uv run pytest -m slow mockstack/tests/live
+
+Linting, formatting, static type checks and the unit tests (with a 90% coverage threshold) are all managed via [pre-commit](https://pre-commit.com/) hooks. Install them once and they will run automatically on every commit:
+
+    uvx pre-commit install
+
+You can invoke these manually on all files with:
+
+    uvx pre-commit run --all-files
 
 
 ## Contributing
 
-If you are contributing to development, you will want to clone this project, and can then install it locally with:
+If you are contributing to development, you will want to clone this project, and can then install it locally (`uv sync` installs the project in editable mode, together with its development dependencies) with:
 
     gh repo clone promptromp/mockstack
     cd mockstack/
     uv sync
-    uv pip install -e .
 
 Run in development mode (for live-reload of changes when developing):
 
     uv run uvicorn --factory mockstack.main:create_app --reload
 
 Note that when you run using the uvicorn CLI, you will need to set any configuration via `.env` file or environment variables.
+
+See [CONTRIBUTING.md](https://github.com/promptromp/mockstack/blob/main/CONTRIBUTING.md) for the full development workflow.