tempest-fastapi-sdk 0.167.0__tar.gz → 0.167.2__tar.gz

tempest_fastapi_sdk-0.167.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug
+description: Algo não se comporta como a documentação diz
+title: "fix: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Obrigado por reportar. Issue é o canal padrão deste repositório — se você
+        quiser implementar a correção, diga isso abaixo e espere o alinhamento
+        antes de abrir PR (a doc PT+EN e o release andam junto com o código).
+  - type: input
+    id: sdk-version
+    attributes:
+      label: Versão do SDK
+      description: 'Saída de `python -c "import tempest_fastapi_sdk as t; print(t.__version__)"`'
+      placeholder: "0.167.1"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Versão do Python
+      placeholder: "3.12.11"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: O que aconteceu
+      description: Inclua o traceback completo, não só a última linha.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: O que você esperava
+      description: E, se aplicável, o trecho da doc que diz isso.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Como reproduzir
+      description: Snippet mínimo e completo — com imports, sem `...`.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: extras
+    attributes:
+      label: Extras instalados
+      placeholder: "[auth,cache,queue] — ou [all]"
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Antes de enviar
+      options:
+        - label: Reproduzi na versão mais recente publicada no PyPI.
+          required: true
+        - label: Procurei uma issue existente sobre o mesmo comportamento.
+          required: true

tempest_fastapi_sdk-0.167.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentação (PT-BR / EN-US)
+    url: https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/
+    about: Tutorial, receitas, exemplos completos e a referência da API — confira antes de abrir a issue.
+  - name: Divulgação de segurança
+    url: mailto:mauricio.benjamin@reloverelations.com
+    about: Relate vulnerabilidades em privado por e-mail, nunca em issue pública.

tempest_fastapi_sdk-0.167.2/.github/ISSUE_TEMPLATE/docs.yml

@@ -0,0 +1,39 @@
+name: Documentação
+description: Página confusa, exemplo que não roda, informação desatualizada ou typo
+title: "docs: "
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Cada página existe duas vezes (`docs/<página>.md` em PT-BR e
+        `docs/<página>.en.md` em EN-US). Por isso a correção sai daqui, aplicada
+        nas duas de uma vez — um PR que arruma só um lado deixa o site
+        inconsistente.
+  - type: input
+    id: page
+    attributes:
+      label: Página
+      description: URL ou caminho do arquivo.
+      placeholder: "https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/permission-guards/"
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: O que está errado
+      description: Cole o trecho e diga o que ele deveria dizer. Se é um exemplo que não roda, inclua o erro.
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Tipo
+      options:
+        - Exemplo não roda / está errado
+        - Informação desatualizada
+        - Explicação confusa ou incompleta
+        - Falta uma página / receita
+        - Typo / formatação
+    validations:
+      required: true

tempest_fastapi_sdk-0.167.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,59 @@
+name: Feature / ideia de API
+description: Uma capacidade nova ou uma mudança na superfície pública
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Descreva o **caso de uso**, não a solução já desenhada — o problema
+        costuma ter uma resposta melhor com as peças que o SDK já tem. O escopo
+        e o formato da API são combinados aqui, antes de existir código.
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Caso de uso
+      description: O que você está construindo e onde o SDK te obriga a escrever código repetido, frágil ou fora do padrão.
+    validations:
+      required: true
+  - type: textarea
+    id: today
+    attributes:
+      label: Como você resolve isso hoje
+      description: O workaround atual, com código se ajudar.
+      render: python
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Ideia de API (opcional)
+      description: Se já imaginou uma assinatura, mostre o call site que gostaria de escrever.
+      render: python
+  - type: dropdown
+    id: area
+    attributes:
+      label: Área do SDK
+      options:
+        - auth / authz
+        - db / repository / migrations
+        - api / middlewares / HTTP
+        - queue / tasks / outbox
+        - cache / flags
+        - admin
+        - genai
+        - geo
+        - storage / upload / download
+        - sse / websocket / webpush
+        - CLI / tooling
+        - docs
+        - outra / não sei
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Antes de enviar
+      options:
+        - label: Verifiquei no [roadmap](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/roadmap/) se já está entregue ou na fila.
+          required: true
+        - label: Procurei uma issue existente com o mesmo pedido.
+          required: true

tempest_fastapi_sdk-0.167.2/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,36 @@
+name: Dúvida de uso
+description: "\"Como faço X com o SDK?\""
+title: "dúvida: "
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Dúvida é bem-vinda como issue: se a resposta não estava na doc, a doc
+        tem um buraco — e a issue costuma virar uma receita ou um trecho novo.
+  - type: textarea
+    id: goal
+    attributes:
+      label: O que você quer fazer
+      description: O objetivo em uma ou duas frases.
+    validations:
+      required: true
+  - type: textarea
+    id: tried
+    attributes:
+      label: O que você já tentou
+      description: Código, se houver, e onde travou.
+      render: python
+  - type: input
+    id: docs-read
+    attributes:
+      label: Páginas da doc que você leu
+      description: Ajuda a saber onde a explicação falhou.
+      placeholder: "recipes/auth-flow, tutorial"
+  - type: input
+    id: sdk-version
+    attributes:
+      label: Versão do SDK
+      placeholder: "0.167.1"
+    validations:
+      required: true

tempest_fastapi_sdk-0.167.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,50 @@
+Tem Script? | Novas Env Vars
+-- | --
+Não/Sim | Não/Sim
+
+> :warning: **NOTA**
+> - <o que precisa ficar saliente para o revisor: migrations, env vars, scripts, integrações externas>
+
+Issue relacionada: #
+
+> Este repositório trabalha com **issue primeiro**: a superfície pública é versionada e a doc PT+EN entra no mesmo commit, então o escopo é combinado na issue antes do código. PR sem issue aceita costuma voltar com um pedido pra abrir uma — veja [Contribuindo](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/contributing/).
+
+## Problema
+
+<por que esse PR existe; o estado anterior, riscos, bugs latentes>
+
+## Solução
+
+<o que foi feito, em sub-seções (### Componente A / ### Componente B) quando faz sentido>
+
+## Screenshots
+
+**Descrição do Screenshot**:
+<descrição da captura, ou "Não se aplica — alterações de backend/tooling/etc.">
+
+## Outras mudanças
+
+<bullets pequenos / "Nenhuma">
+
+## Notas sobre deploy
+
+<passos de deploy, rebuilds necessários, validação local executada>
+
+**Validação local executada**:
+- <comandos rodados (testes, build, lint) com resultado>
+
+**Novas Variáveis de Ambiente**:
+- Nenhuma | <nome>: <descrição>
+
+**Novos Scripts e/ou Tarefas de Background**:
+- Nenhum | <descrição>
+
+**Novas Dependências**:
+- Nenhuma | <pacote@versão>: <motivo>
+
+**Documentação** (obrigatório quando muda superfície pública):
+- [ ] `README.md`
+- [ ] `CHANGELOG.md`
+- [ ] receita / página em `docs/<página>.md` **e** `docs/<página>.en.md`
+- [ ] stub em `docs/reference.md` para cada símbolo público novo
+- [ ] `uv run --group docs mkdocs build --strict` verde

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.2}/CHANGELOG.md

@@ -5,6 +5,84 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.167.2] — 2026-07-26
+
+Documentation layout only — no code change, no API change.
+
+### Changed
+
+- **The tab bar is down from 13 tabs to 11, and every section is reachable from
+  the landing page.** `Exemplos` and `SSR (páginas tipadas)` were loose
+  top-level nav entries, which crowded the Material tab bar; the landing page
+  meanwhile pointed only at Installation / Architecture / Tutorial, so Recipes,
+  Reference and Learning projects existed on the bar and nowhere in the prose.
+  Both fixed:
+    - `Exemplos` is gone as a tab. The five integrated walkthroughs (Pix
+      checkout, neighborhood marketplace, full store admin, fullstack web,
+      GenAI flows) now live under **Recipes** as the `Exemplos completos` /
+      `Complete examples` sub-section, and are indexed in a table on the
+      Recipes landing. Their URLs are unchanged.
+    - `SSR (páginas tipadas)` is now a recipe, listed in the Recipes index
+      alongside the others. URL unchanged.
+    - The **SDK tour** was merged into the Recipes landing
+      (`docs/recipes/index.md`) as its opening section, so one page is the
+      entry point instead of two competing for the role. `docs/tour.md` /
+      `docs/tour.en.md` are removed and the `/tour/` URL is gone — inbound
+      links now target the tour section of the Recipes landing.
+    - The Recipes index table covers **all 53 recipes**; twelve were missing
+      (`authz`, `permission-guards`, `introspection-auth`, `geo`, `genai`,
+      `file-store`, `artifact-registry`, `openapi-errors`, `openapi-client`,
+      `system-checks`, `management-commands`, `react-spa`) plus SSR.
+    - The landing page gained a **"Por onde continuar" / "Where to go next"**
+      card grid naming every section — Installation, Architecture, Tutorial,
+      Recipes, Reference, Learning projects, Roadmap, Migration guide and
+      Changelog — and its stale Status row (`630+ tests, ≥ 89 %`) now reads
+      `2.650+ / ≥ 90 %`.
+- **Contributing is issue-first.** The page now opens with the policy: the
+  useful contribution is an issue, not a PR, because the public surface is
+  versioned and the bilingual docs ship in the same commit as the code. It
+  explains what makes an issue actionable, why the ordering exists, and what a
+  PR needs *after* an issue is accepted. "Docs typo → PR straight against
+  `docs/<page>.md`" is gone: a fix touching only one of the two language
+  mirrors leaves the site inconsistent, so typos are issues too.
+
+### Added
+
+- **GitHub issue forms** under `.github/ISSUE_TEMPLATE/` — bug, feature / API
+  idea, documentation and usage question — with `config.yml` disabling blank
+  issues and pointing at the docs site and the private security contact. Plus a
+  `PULL_REQUEST_TEMPLATE.md` carrying the project's PT-BR PR shape and a
+  documentation checklist.
+
+## [0.167.1] — 2026-07-26
+
+### Fixed
+
+- **`BaseController` now accepts services typed over a concrete update
+  schema.** `ServiceT`'s bound was written `BaseService[Any, Any]`, which is not
+  a partial application: PEP 696 fills the omitted `UpdateT` with its
+  `BaseSchema` default, and since that parameter is invariant the bound admitted
+  only services whose update schema was exactly `BaseSchema`. Every service
+  written the documented way — `BaseService[Repo, Resp, MyUpdateSchema]` — was
+  rejected by the type checker with `Type parameter "UpdateT@BaseService" is
+  invariant, but "MyUpdateSchema" is not the same as "BaseSchema"`, forcing a
+  `# type: ignore[type-var]` on the controller declaration. The bound is now
+  `BaseService[Any, Any, Any]`, which leaves the invariant parameter open while
+  keeping the `BaseSchema` constraint. Type-check only — runtime behavior is
+  unchanged, and the `# type: ignore[type-var]` workarounds can be dropped.
+- **The suite can now see this class of bug.** `mypy` runs over the package, not
+  over `tests/`, so `tests/controllers/test_base.py` already declared exactly
+  this service/controller pair and stayed green. New
+  `tests/controllers/test_generic_bounds.py` inspects `ServiceT.__bound__`
+  directly and runs `mypy --strict` over a downstream-shaped snippet, asserting
+  no `[type-var]` diagnostic.
+
+### Documentation
+
+- `docs/architecture.md` / `docs/architecture.en.md` — the controllers & services
+  section now shows the 3rd generic parameter on both layers and notes that the
+  pair requires 0.167.1+.
+
 ## [0.167.0] — 2026-07-26
 
 Permission guards: a decorator that runs plain `(user) -> user | None`

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.167.0
+Version: 0.167.2
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.2}/docs/architecture.en.md

@@ -163,6 +163,31 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `update(id, data)` | `service.update` | Same. |
 | `delete(id)` | `service.delete` | Same. |
 
+!!! tip "Typing the `update` payload end to end"
+    The 3rd generic parameter is the update schema, and it must be the **same** on both layers: a service declared as `BaseService[Repo, Resp, MyUpdateSchema]` fits `BaseController[MyService, Resp, MyUpdateSchema]`. Omit the 3rd parameter on either one and it falls back to the `BaseSchema` default, leaving `update`'s `data` loosely typed.
+
+    ```python
+    from tempest_fastapi_sdk import BaseController, BaseService
+
+    from src.db.repositories import CoinPackRepository
+    from src.schemas import CoinPackResponseSchema, CoinPackUpdateSchema
+
+
+    class CoinPackService(
+        BaseService[CoinPackRepository, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Service typed over the concrete update schema."""
+
+
+    class CoinPackController(
+        BaseController[CoinPackService, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Controller repeating the same update schema."""
+    ```
+
+    !!! warning "Requires 0.167.1+"
+        On earlier versions this pair failed type checking with `Type parameter "UpdateT@BaseService" is invariant, but "CoinPackUpdateSchema" is not the same as "BaseSchema"` — `ServiceT`'s bound pinned that invariant parameter to `BaseSchema`. Fixed in 0.167.1; nothing changes at runtime.
+
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.
 
 ```python

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.2}/docs/architecture.md

@@ -163,6 +163,31 @@ O que você herda ao subclassear `BaseController[ServiceT, ResponseT]`:
 | `update(id, data)` | `service.update` | Igual. |
 | `delete(id)` | `service.delete` | Igual. |
 
+!!! tip "Tipando o payload de `update` ponta a ponta"
+    O 3º parâmetro genérico é o schema de update, e ele precisa ser o **mesmo** nas duas camadas: um service declarado como `BaseService[Repo, Resp, MeuUpdateSchema]` encaixa em `BaseController[MeuService, Resp, MeuUpdateSchema]`. Omitir o 3º parâmetro em qualquer uma delas cai no default `BaseSchema`, e o `data` de `update` chega sem tipo preciso.
+
+    ```python
+    from tempest_fastapi_sdk import BaseController, BaseService
+
+    from src.db.repositories import CoinPackRepository
+    from src.schemas import CoinPackResponseSchema, CoinPackUpdateSchema
+
+
+    class CoinPackService(
+        BaseService[CoinPackRepository, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Service tipado sobre o schema de update concreto."""
+
+
+    class CoinPackController(
+        BaseController[CoinPackService, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Controller que repete o mesmo schema de update."""
+    ```
+
+    !!! warning "Requer 0.167.1+"
+        Em versões anteriores esse par falhava no type check com `Type parameter "UpdateT@BaseService" is invariant, but "CoinPackUpdateSchema" is not the same as "BaseSchema"` — o bound de `ServiceT` deixava o parâmetro invariante fixado em `BaseSchema`. Corrigido em 0.167.1; nada muda em runtime.
+
 Quando um caso de uso precisa de regras de domínio, sobrescreva o método herdado no service. Quando um caso de uso precisa coordenar mais de um service, sobrescreva o método herdado (ou adicione um novo) no controller. O router nunca cresce — ele só depende do controller.
 
 ```python

tempest_fastapi_sdk-0.167.2/docs/contributing.en.md

@@ -0,0 +1,121 @@
+# Contributing
+
+!!! tip "The most useful contribution is an issue — not a PR"
+    This SDK is a **versioned public surface**: every release publishes to PyPI, and every new symbol carries a docstring, bilingual docs and a reference entry. So the flow here is **issue first**: you describe the problem (or the idea), we agree on the scope and the shape, and only then does anyone write code. A PR that arrives before that agreement almost always has to be redone.
+
+    **[Open an issue »](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new/choose)**
+
+## Open an issue
+
+| Need | Where |
+| --- | --- |
+| Bug (something does not behave as documented) | [Issue: bug report](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=bug_report.yml) |
+| Feature / API idea | [Issue: feature request](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=feature_request.yml) |
+| Confusing or incomplete docs, an example that does not run, a typo | [Issue: docs](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=docs.yml) |
+| Usage question ("how do I do X with the SDK?") | [Issue: question](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=question.yml) |
+| Security disclosure | mauricio.benjamin@reloverelations.com (private, **never** a public issue) |
+
+What makes an issue get resolved fast:
+
+- the **SDK version** (`python -c "import tempest_fastapi_sdk as t; print(t.__version__)"`) and the Python version;
+- a **minimal snippet** that reproduces it — complete, with imports, no `...`;
+- **what you expected** and **what happened** (the whole traceback, not its last line);
+- for a feature: the **use case**, not a solution already designed. The problem often has a better answer built from pieces the SDK already ships.
+
+!!! note "A docs typo is an issue too"
+    It used to say "send a PR straight away". Not anymore: every page exists **twice** (`docs/<page>.md` in PT-BR and `docs/<page>.en.md` in EN-US), and a PR fixing only one side leaves the site inconsistent. Open the issue pointing at the page and the passage — the fix lands in both at once.
+
+## Why an issue comes before code
+
+Three constraints of this repository that never show up in a diff:
+
+1. **Versioning and compatibility.** Every public symbol lands in `__all__`, in the rendered reference and in the SemVer contract. Renaming it or changing its signature later is a breaking change with a migration guide.
+2. **Docs in the same commit.** A public-surface change without README, `CHANGELOG.md`, the bilingual recipe and the reference stub updated does not pass — that is a project rule, not a reviewer's preference.
+3. **One release per feature.** Each slice ships as its own version (bump in `pyproject.toml`, `__version__` and `uv.lock`, full gates, tag). The maintainer drives that cycle.
+
+None of this blocks your contribution — it just means **agreeing on the scope in the issue is faster** than discovering it during PR review.
+
+## I want to implement it
+
+Great — say so **in the issue** and wait for the go-ahead. Then:
+
+- work on a `feat/<slug>` / `fix/<slug>` branch off `main`;
+- run `make check` (lint + format + mypy + tests) — CI runs the same target on 3.11 / 3.12 / 3.13;
+- update the PT **and** EN docs along with the code, plus `CHANGELOG.md`;
+- do **not** bump the version or create a tag — that belongs to the release;
+- one PR per topic, with a body that states the problem before the solution.
+
+A PR without an accepted issue is usually closed with a request to open one — that is not a rejection of the work, it is the ordering that keeps the docs and the release coherent.
+
+## Development environment
+
+```bash
+# Clone + sync every extra and the dev/docs groups
+git clone https://github.com/mauriciobenjamin700/tempest-fastapi-sdk.git
+cd tempest-fastapi-sdk
+uv sync --all-extras --group dev --group docs
+```
+
+!!! tip "Quick verification"
+    `make check` runs the full quality gate (lint + format check + mypy + pytest). CI runs the same target on every push, so a green `make check` locally means a green PR.
+
+## Quality gates
+
+| Command | What it does |
+| --- | --- |
+| `make lint` | `ruff check .` (no auto-fix) |
+| `make fix` | `ruff check --fix .` + `ruff format .` (writes) |
+| `make fmt` | `ruff format .` (writes) |
+| `make fmt-check` | `ruff format --check .` (read-only) |
+| `make type` | `mypy tempest_fastapi_sdk` (strict) |
+| `make test` | `pytest` with coverage |
+| `make check` | `lint + fmt-check + type + test` (stops at first failure) |
+| `make ci` | `check + build + smoke` (full CI mirror) |
+
+The same gates are available through the bundled CLI: `tempest lint` / `tempest fix` / `tempest check` work in any consumer project too.
+
+## Tests
+
+```bash
+make test                    # full suite + coverage
+uv run pytest tests/admin    # the admin module only
+uv run pytest -k cursor      # tests matching "cursor"
+uv run pytest -x             # stop at the first failure
+```
+
+The suite uses in-memory SQLite via `tempest_fastapi_sdk.testing.test_session`. Repository tests share the `session` fixture from `tests/conftest.py`.
+
+## Docs
+
+```bash
+make docs-serve              # mkdocs serve — live reload at http://127.0.0.1:8000
+make docs-build              # build the static site into ./site/
+```
+
+Every page lives in two languages (`docs/<page>.md` + `docs/<page>.en.md`) and the build runs with `--strict` — a warning is an error. Edits reach the Pages site on push to `main` via [`.github/workflows/docs.yml`](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/blob/main/.github/workflows/docs.yml).
+
+## Commit message style
+
+Conventional Commits prefixes:
+
+- `feat:` — new user-facing capability
+- `fix:` — bug fix
+- `refactor:` — internal restructuring with no behavior change
+- `docs:` — documentation only
+- `style:` — formatting / whitespace
+- `tests:` — test-only changes
+- `chore:` — tooling, deps, release plumbing
+
+Add `!` after the prefix for breaking changes (`feat!: drop class-attr config`). Note in the message which version delivers the change.
+
+## Release (maintainer)
+
+`make release VERSION=X.Y.Z` bumps the version locations, runs every gate, creates the commit + tag and tells you what to push:
+
+```bash
+make release VERSION=0.20.0
+git push origin main
+git push origin v0.20.0
+```
+
+The PyPI publish workflow fires on the `vX.Y.Z` tag push (trusted publishing — no API token in the repository).

tempest_fastapi_sdk-0.167.2/docs/contributing.md

@@ -0,0 +1,121 @@
+# Contribuindo
+
+!!! tip "A contribuição mais útil é uma issue — não um PR"
+    Este SDK é uma **superfície pública versionada**: cada release publica no PyPI e cada símbolo novo carrega docstring, docs bilíngues e entrada na referência. Por isso o fluxo aqui é **issue primeiro**: você descreve o problema (ou a ideia), a gente combina o escopo e o formato, e só então alguém escreve código. Um PR que chega antes desse alinhamento quase sempre precisa ser refeito.
+
+    **[Abrir uma issue »](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new/choose)**
+
+## Abra uma issue
+
+| Necessidade | Onde |
+| --- | --- |
+| Bug (algo não funciona como documentado) | [Issue: bug report](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=bug_report.yml) |
+| Feature / ideia de API | [Issue: feature request](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=feature_request.yml) |
+| Doc confusa, incompleta, exemplo que não roda, typo | [Issue: docs](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=docs.yml) |
+| Dúvida de uso ("como faço X com o SDK?") | [Issue: dúvida](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/issues/new?template=question.yml) |
+| Divulgação de segurança | mauricio.benjamin@reloverelations.com (privado, **nunca** em issue pública) |
+
+O que faz uma issue ser resolvida rápido:
+
+- **versão do SDK** (`python -c "import tempest_fastapi_sdk as t; print(t.__version__)"`) e do Python;
+- **snippet mínimo** que reproduz — completo, com imports, sem `...`;
+- **o que você esperava** e **o que aconteceu** (traceback inteiro, não a última linha);
+- para feature: **o caso de uso**, não a solução já desenhada. O problema costuma ter uma resposta melhor com as peças que o SDK já tem.
+
+!!! note "Typo na doc também é issue"
+    Antes era "manda PR direto". Não mais: cada página existe **duas vezes** (`docs/<página>.md` em PT-BR e `docs/<página>.en.md` em EN-US) e um PR que corrige só um lado deixa o site inconsistente. Abra a issue apontando a página e o trecho — a correção sai nas duas de uma vez.
+
+## Por que issue antes de código
+
+Três restrições deste repositório que não aparecem no diff:
+
+1. **Versionamento e compatibilidade.** Todo símbolo público entra em `__all__`, na referência renderizada e no contrato SemVer. Renomear ou mudar assinatura depois é breaking change com guia de migração.
+2. **Docs no mesmo commit.** Mudança de superfície pública sem README, `CHANGELOG.md`, receita bilíngue e stub de referência atualizados não passa — é regra do projeto, não preferência do revisor.
+3. **Release por feature.** Cada fatia sai como sua própria versão (bump em `pyproject.toml`, `__version__` e `uv.lock`, gates completos, tag). Quem conduz esse ciclo é o mantenedor.
+
+Nada disso impede sua contribuição — só significa que **combinar o escopo na issue é mais rápido** do que descobrir na revisão do PR.
+
+## Quero implementar
+
+Ótimo — diga isso **na issue** e espere o "vai". Aí:
+
+- trabalhe num branch `feat/<slug>` / `fix/<slug>` a partir de `main`;
+- rode `make check` (lint + formato + mypy + testes) — o CI roda o mesmo alvo em 3.11 / 3.12 / 3.13;
+- atualize a doc PT **e** EN junto com o código, mais `CHANGELOG.md`;
+- **não** faça bump de versão nem crie tag — isso é do release;
+- um PR por assunto, com o corpo explicando o problema antes da solução.
+
+PR sem issue aceita costuma ser fechado com um pedido pra abrir a issue — não é rejeição do trabalho, é a ordem que mantém a doc e o release coerentes.
+
+## Ambiente de desenvolvimento
+
+```bash
+# Clone + sincronize todos os extras e os grupos dev/docs
+git clone https://github.com/mauriciobenjamin700/tempest-fastapi-sdk.git
+cd tempest-fastapi-sdk
+uv sync --all-extras --group dev --group docs
+```
+
+!!! tip "Verificação rápida"
+    `make check` roda o gate de qualidade completo (lint + checagem de formato + mypy + pytest). O CI roda o mesmo alvo em cada push, então um `make check` verde localmente significa um PR verde.
+
+## Gates de qualidade
+
+| Comando | O que faz |
+| --- | --- |
+| `make lint` | `ruff check .` (sem auto-fix) |
+| `make fix` | `ruff check --fix .` + `ruff format .` (escreve) |
+| `make fmt` | `ruff format .` (escreve) |
+| `make fmt-check` | `ruff format --check .` (somente leitura) |
+| `make type` | `mypy tempest_fastapi_sdk` (strict) |
+| `make test` | `pytest` com cobertura |
+| `make check` | `lint + fmt-check + type + test` (para no primeiro erro) |
+| `make ci` | `check + build + smoke` (espelho completo do CI) |
+
+Os mesmos gates estão disponíveis pela CLI embutida: `tempest lint` / `tempest fix` / `tempest check` funcionam em qualquer projeto consumidor também.
+
+## Testes
+
+```bash
+make test                    # suite completa + cobertura
+uv run pytest tests/admin    # só o módulo admin
+uv run pytest -k cursor      # testes que casam com "cursor"
+uv run pytest -x             # para no primeiro erro
+```
+
+A suite usa SQLite em memória via `tempest_fastapi_sdk.testing.test_session`. Os testes de repository compartilham a fixture `session` de `tests/conftest.py`.
+
+## Docs
+
+```bash
+make docs-serve              # mkdocs serve — live reload em http://127.0.0.1:8000
+make docs-build              # build do site estático em ./site/
+```
+
+Toda página vive em duas línguas (`docs/<página>.md` + `docs/<página>.en.md`) e o build roda com `--strict` — warning é erro. As edições caem no site do Pages no push para `main` via [`.github/workflows/docs.yml`](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk/blob/main/.github/workflows/docs.yml).
+
+## Estilo das mensagens de commit
+
+Prefixos de Conventional Commits:
+
+- `feat:` — nova capacidade voltada ao usuário
+- `fix:` — correção de bug
+- `refactor:` — reestruturação interna sem mudança de comportamento
+- `docs:` — só documentação
+- `style:` — formatação / espaços
+- `tests:` — só mudanças de teste
+- `chore:` — tooling, deps, encanamento de release
+
+Adicione `!` após o prefixo para mudanças que quebram compatibilidade (`feat!: drop class-attr config`). Marque na mensagem a versão que entrega a mudança.
+
+## Release (mantenedor)
+
+`make release VERSION=X.Y.Z` faz o bump nas localizações da versão, roda todos os gates, cria o commit + tag e diz o que você deve dar push:
+
+```bash
+make release VERSION=0.20.0
+git push origin main
+git push origin v0.20.0
+```
+
+O workflow de publicação no PyPI dispara no push da tag `vX.Y.Z` (publicação confiável — sem token de API no repositório).