nene2-python 1.8.66__tar.gz → 1.8.163__tar.gz

{nene2_python-1.8.66 → nene2_python-1.8.163}/.env.example

@@ -35,6 +35,11 @@ CORS_ORIGINS=[]
 # DB_USER=nene2
 # DB_PASSWORD=secret
 
+# レートリミット（APP_ENV=local では未設定時オフ。有効化する場合のみ）
+# THROTTLE_ENABLED=true
+# THROTTLE_LIMIT=60
+# THROTTLE_WINDOW=60
+
 # デフォルト値
 DB_ADAPTER=sqlite
 DB_NAME=:memory:

{nene2_python-1.8.66 → nene2_python-1.8.163}/.github/workflows/ci.yml

@@ -50,3 +50,31 @@ jobs:
         # PYSEC-2025-183: pyjwt weak-key-length — disputed by supplier, no fix version available.
         # Transitive via mcp>=1.0. Re-evaluate when pyjwt releases a fix. (#280)
         run: uv run pip-audit --ignore-vuln PYSEC-2025-183
+
+  package-build:
+    name: Package build verification
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      # publish.yml と同じ uv build を PR ごとに走らせ、配布物の壊れを早期検出する（#541）。
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Validate distribution metadata (twine check)
+        run: uvx twine check dist/*
+
+      - name: Verify clean install + import (no example/tests leakage)
+        run: |
+          uv venv /tmp/verify
+          uv pip install --python /tmp/verify/bin/python dist/*.whl
+          /tmp/verify/bin/python -c "import nene2; from nene2.http import PaginationResponse; print('import OK')"
+          # フレームワーク以外（example/tests）が配布物に混入していないことを保証
+          if /tmp/verify/bin/python -c "import example" 2>/dev/null; then
+            echo "ERROR: example package leaked into wheel"; exit 1
+          fi

{nene2_python-1.8.66 → nene2_python-1.8.163}/AGENTS.md

@@ -10,7 +10,8 @@ NENE2 の設計哲学を Python で実装したリファレンスフレームワ
 - DTO / バリデーション: Pydantic v2 + `dataclass(frozen=True)`
 - 型チェック: `mypy --strict`
 - Lint / Format: `ruff`
-- テスト: `pytest` + `httpx`
+- テスト: `pytest` + `httpx`（466 tests、カバレッジ 80% 以上）
+- 現状: **v1.8.97** / FT219 完了 / [Field Trial INDEX](docs/field-trials/INDEX.md)
 
 ## 設計原則（PHP 版 NENE2 と共通）
 
@@ -19,13 +20,28 @@ NENE2 の設計哲学を Python で実装したリファレンスフレームワ
 3. ハンドラーは薄く: parse → use-case → response
 4. エラーは RFC 9457 Problem Details（application/problem+json）
 5. `ValidationException` → 422 自動マッピング
+6. FastAPI アプリは `APIRouter` + `create_app()` をファイル末尾に配置（[CLAUDE.md](CLAUDE.md)）
 
 ## 全チェックコマンド（CI と同等）
 
 ```bash
-uv run pytest && uv run mypy src/ && uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/
+uv run pytest && \
+uv run mypy src/ && \
+uv run ruff check src/ tests/ && \
+uv run ruff format --check src/ tests/ && \
+uv run pip-audit --ignore-vuln PYSEC-2025-183
 ```
 
+## ドキュメント入口
+
+| 用途 | ファイル |
+|---|---|
+| 設計ポリシー（SSOT） | [CLAUDE.md](CLAUDE.md) |
+| 現状・次タスク | [docs/todo/current.md](docs/todo/current.md) |
+| FT 一覧 | [docs/field-trials/INDEX.md](docs/field-trials/INDEX.md) |
+| API リファレンス | [docs/reference/framework-modules.md](docs/reference/framework-modules.md) |
+| How-to | [docs/how-to/](docs/how-to/) |
+
 ## PHP 版リポジトリとの関係
 
 PHP 版 NENE2 の設計決定・ADR・フィールドトライアル記録は `../NENE2/docs/` を参照。

{nene2_python-1.8.66 → nene2_python-1.8.163}/CHANGELOG.md

@@ -3,6 +3,36 @@
 All notable changes to nene2-python are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+> 詳細な版ごとの一行サマリーは [`docs/todo/current.md`](docs/todo/current.md) の
+> マイルストーン表を参照。本ファイルにはリリース粒度の集約エントリを記録する。
+
+---
+
+## [1.8.163] — 2026-05-29
+
+v1.8.35〜v1.8.163 の集約リリース。フィールドトライアル網羅スイープの完了と、
+公開準備・ポリシー整合・ハウスキーピングを含む。
+
+### Added
+- フィールドトライアル **FT203〜FT282**（標準ライブラリ検証 + セキュリティ深掘り）。
+  セキュリティ診断（`%3==0`）・クラッカーペンテスト（`%4==0`）・6 ペルソナ DX レビューを各 FT で実施。
+  危険プリミティブ回避シリーズ（pickle/marshal/eval、subprocess、SSRF、ReDoS、zip/tar slip、解凍爆弾、SSTI、XXE 等）を含む。
+- FT ループ方法論ドキュメント [`docs/explanation/field-trial-methodology.md`](docs/explanation/field-trial-methodology.md)（EN/JA）— 目的・3 フェーズ・終着点を明文化 (#540)
+- ETag / 条件付きリクエスト、`CompositeAuthMiddleware`、`InMemoryRateLimitStorage`、query ヘルパー、`LocalTokenIssuer`、`RequestScopedContext`
+- リリース手順 how-to [`docs/how-to/release-and-publish.md`](docs/how-to/release-and-publish.md)、CI に配布物ビルド検証ジョブ (#541)
+
+### Changed
+- example の全ハンドラー（Note/Tag/Comment）に `response_model` を付与し OpenAPI にレスポンス型を出力 (#539)
+- starlette 1.0.1 へ更新（PYSEC-2026-161 解消、#611）
+
+### Fixed
+- example の 422 レスポンスで全フィールドのエラーを返すように修正 (#588)
+- `APP_ENV=local` で throttle を既定無効化 (#592)
+
+### Housekeeping
+- FT サンドボックスを 5.1G→79M に整理（`ft-status.sh --clean-sandbox` 追加）、マージ済み orphan ブランチを削除
+- #553（`/examples/ping`・`/examples/notes`）は #578 で実装済みを確認し close
+
 ---
 
 ## [1.8.34] — 2026-05-20

{nene2_python-1.8.66 → nene2_python-1.8.163}/CLAUDE.md

@@ -223,7 +223,14 @@ AI エージェント（Claude 等）がこのコードベースを正確に理
 ## 7. エラーハンドリングポリシー
 
 - `ValidationException` → 422 validation-failed Problem Details（自動）
-- `ErrorHandlerMiddleware` が全例外をキャッチ
+  - `ValidationError` は **`field / message / code` の 3 引数がすべて必須**（省略すると TypeError）
+  ```python
+  from nene2.validation import ValidationError, ValidationException
+  raise ValidationException([
+      ValidationError(field="host", message="許可されていません", code="host_not_allowed")
+  ])
+  ```
+- `ErrorHandlerMiddleware` が全例外をキャッチ（FT サンドボックスでも `add_middleware(ErrorHandlerMiddleware)` を忘れないこと）
 - `APP_DEBUG=true` 時のみ例外メッセージを detail に含める
 - **スタックトレース・DB 接続情報を公開レスポンスに含めない**
 - ログには `logging` モジュールのみ使用（`print()` 禁止）
@@ -319,7 +326,7 @@ uv run pytest && \
 uv run mypy src/ && \
 uv run ruff check src/ tests/ && \
 uv run ruff format --check src/ tests/ && \
-uv run pip-audit
+uv run pip-audit --ignore-vuln PYSEC-2025-183
 
 # 個別
 uv run pytest
@@ -329,7 +336,7 @@ uv run mypy src/
 uv run ruff check src/ tests/
 uv run ruff check src/ tests/ --fix          # 自動修正
 uv run ruff format src/ tests/
-uv run pip-audit                             # 依存関係の脆弱性スキャン
+uv run pip-audit --ignore-vuln PYSEC-2025-183  # 依存関係の脆弱性スキャン（CI と同じ）
 
 # 開発サーバー
 uv run uvicorn src.example.app:app --reload --port 8080
@@ -345,11 +352,13 @@ docker compose up app
 ```
 src/
   nene2/              フレームワークコア
-    http/             JSON レスポンス・ページネーション・Problem Details
-    middleware/       ミドルウェアパイプライン（Error / Security / RequestId / Logging / SizeLimit / Throttle）
+    http/             JSON レスポンス・ページネーション・Problem Details・ETag・query ヘルパー
+    middleware/       ミドルウェアパイプライン + setup_middlewares()
     validation/       ValidationException / ValidationError
     config/           型付き設定オブジェクト（AppSettings）
-    auth/             TokenVerifierProtocol / BearerTokenMiddleware / ApiKeyAuthMiddleware
+    auth/             Bearer / API Key / CompositeAuth / LocalTokenIssuer
+    cache/            TtlCache[V]
+    security/         verify_hmac_signature()
     database/         SqlAlchemyQueryExecutor / SqlAlchemyTransactionManager
     mcp/              LocalMcpServer / HttpxMcpClient
     log/              structlog セットアップ
@@ -358,20 +367,24 @@ src/
     note/             Note ドメイン（entity / repository / use_case / handler / sqlalchemy_repository）
     tag/              Tag ドメイン（entity / repository / use_case / handler / sqlalchemy_repository）
     comment/          Comment ドメイン（Note に紐付く nested ドメイン）
-    app.py            アプリケーションファクトリ
+    app.py            アプリケーションファクトリ（create_app）
     mcp.py            MCP サーバー（Note / Tag / Comment 全 15 ツール）
 
-tests/                pytest テスト（src/ を鏡像）
+tests/                pytest テスト（src/ を鏡像、466 tests）
 docs/
   adr/                設計決定記録（変更理由を残す）
-  how-to/             How-to ガイド
+  how-to/             How-to ガイド（24+ 本）
   howto/              MCP セットアップガイド
-  field-trials/       フィールドトライアル記録（FT1〜FT3）
+  field-trials/       フィールドトライアル記録（FT1〜FT219+、INDEX.md 参照）
+  field-trials/INDEX.md  FT 検索索引（テーマ・診断種別・Follow-up Issue）
+  todo/current.md     現状サマリー・次タスク
+  roadmap.md          ロードマップ・PHP 版対応表
+  review/             作業日報
   tutorials/          チュートリアル
   explanation/        アーキテクチャ解説
   reference/          設定・モジュールリファレンス
   ja/                 日本語ドキュメント（上記すべての翻訳）
-.github/workflows/    CI（GitHub Actions）
+.github/workflows/    CI（GitHub Actions: Python 3.12 / 3.14）
 ```
 
 ---
@@ -476,4 +489,4 @@ Python 標準ライブラリ・サードパーティライブラリを nene2-pyt
 | `JsonResponseFactory` | `fastapi.responses.JSONResponse` |
 | `PHPStan level 8` | `mypy --strict` |
 | `PHP-CS-Fixer` | `ruff format` |
-| `composer check` | `uv run pytest && mypy && ruff check && ruff format --check && pip-audit` |
+| `composer check` | `uv run pytest && mypy && ruff check && ruff format --check && pip-audit --ignore-vuln PYSEC-2025-183` |

{nene2_python-1.8.66 → nene2_python-1.8.163}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.66
+Version: 1.8.163
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python
-Project-URL: Documentation, https://github.com/hideyukiMORI/nene2-python/tree/main/docs
+Project-URL: Documentation, https://hideyukimori.github.io/nene2-python/
 Project-URL: Bug Tracker, https://github.com/hideyukiMORI/nene2-python/issues
 Author-email: hideyukiMORI <info.xion.cc@gmail.com>
 License: MIT
@@ -18,6 +18,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
@@ -51,6 +52,8 @@ A Python reference framework implementing the [NENE2](https://github.com/hideyuk
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
+**Current release**: `v1.8.97` · **466 tests** · CI on Python 3.12 and 3.14
+
 ---
 
 ## Features
@@ -60,11 +63,14 @@ A Python reference framework implementing the [NENE2](https://github.com/hideyuk
 - **`mypy --strict`** — equivalent to PHPStan level 8 type safety
 - **ruff** — lint and format in one tool (replaces flake8, isort, black, bandit)
 - **RFC 9457 Problem Details** — uniform error responses across all endpoints
-- **Bearer Token / API Key auth** — zero-config `LocalTokenVerifier`
+- **Bearer Token / API Key auth** — `LocalTokenVerifier`, `CompositeAuthMiddleware`, dev JWT helpers
 - **MCP support** — expose UseCases as AI agent tools via `LocalMcpServer`
 - **SQLAlchemy Core** — parameterised SQL without ORM overhead
-- **Security middleware** — CSP, X-Frame-Options, rate limiting, request size limit, CORS
+- **Security middleware** — CSP, rate limiting, request size limit, CORS via `setup_middlewares()`
+- **ETag / conditional requests** — `generate_etag()`, `check_not_modified()`, `check_precondition()`
+- **TTL cache & webhooks** — `TtlCache[V]`, `verify_hmac_signature()`
 - **structlog** — structured JSON logging with request ID correlation
+- **219 field trials** — stdlib and framework patterns validated in sandbox apps ([INDEX](docs/field-trials/INDEX.md))
 
 ---
 
@@ -76,31 +82,44 @@ pip install nene2-python
 uv add nene2-python
 ```
 
-Requires Python 3.12+.
+Requires Python 3.12+ (CI also tests 3.14).
 
 ---
 
 ## Quick Start
 
+Use `APIRouter` + `create_app()` at the **end of the file** (see [CLAUDE.md](CLAUDE.md)). Register middlewares with `setup_middlewares()` so 500 responses still get `X-Request-Id` and security headers.
+
 ```python
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI
 from nene2.config import AppSettings
-from nene2.middleware import (
-    ErrorHandlerMiddleware,
-    RequestIdMiddleware,
-    SecurityHeadersMiddleware,
-    ThrottleMiddleware,
-)
-
-cfg = AppSettings()
-app = FastAPI()
-
-app.add_middleware(ErrorHandlerMiddleware, debug=cfg.app_debug)
-app.add_middleware(SecurityHeadersMiddleware)
-app.add_middleware(RequestIdMiddleware)
-app.add_middleware(ThrottleMiddleware, limit=cfg.throttle_limit, window=cfg.throttle_window)
+from nene2.middleware import setup_middlewares
+
+router = APIRouter()
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+def create_app() -> FastAPI:
+    cfg = AppSettings()
+    app = FastAPI(title=cfg.app_name)
+    setup_middlewares(
+        app,
+        debug=cfg.app_debug,
+        throttle_limit=cfg.throttle_limit if cfg.throttle_enabled else None,
+        cors_allowed_origins=cfg.cors_origins if cfg.cors_enabled else None,
+    )
+    app.include_router(router)
+    return app
+
+app = create_app()
 ```
 
+See the full reference app in [`src/example/`](src/example/) (Note / Tag / Comment CRUD, auth, MCP).
+
+---
+
 ### Define a domain
 
 ```python
@@ -137,7 +156,6 @@ class GetNoteUseCase:
 ```python
 from fastapi import APIRouter
 from fastapi.responses import JSONResponse
-from nene2.http import problem_details_response
 
 router = APIRouter(prefix="/notes", tags=["notes"])
 
@@ -147,16 +165,14 @@ async def get_note(note_id: int) -> JSONResponse:
     return JSONResponse({"id": note.id, "title": note.title, "body": note.body})
 ```
 
-See the full working example in [`src/example/`](src/example/).
-
 ---
 
 ## Development Commands
 
 ```bash
 uv sync                         # install dependencies
-uv run pytest                   # run tests (coverage enforced at 80%)
-uv run mypy src/                # type check
+uv run pytest                   # 466 tests, coverage ≥ 80%
+uv run mypy src/                # type check (strict)
 uv run ruff check src/ tests/   # lint
 uv run ruff format src/ tests/  # format
 uv run uvicorn src.example.app:app --reload --port 8080  # dev server
@@ -169,25 +185,39 @@ uv run pytest && \
 uv run mypy src/ && \
 uv run ruff check src/ tests/ && \
 uv run ruff format --check src/ tests/ && \
-uv run pip-audit
+uv run pip-audit --ignore-vuln PYSEC-2025-183
 ```
 
+CI also runs a **90% coverage gate** on `example/*/use_case.py`, `entity.py`, and `async_use_case.py`.
+
 ---
 
 ## Framework Modules
 
 | Module | Purpose |
 |---|---|
-| `nene2.http` | `PaginationQueryParser`, `PaginationResponse`, `problem_details_response()` |
-| `nene2.middleware` | `ErrorHandlerMiddleware`, `SecurityHeadersMiddleware`, `RequestIdMiddleware`, `RequestLoggingMiddleware`, `RequestSizeLimitMiddleware`, `ThrottleMiddleware` |
-| `nene2.auth` | `BearerTokenMiddleware`, `ApiKeyAuthMiddleware`, `LocalTokenVerifier`, `TokenVerifierProtocol` |
+| `nene2.http` | Pagination, Problem Details, health checks, ETag, query helpers, `RequestScopedContext` |
+| `nene2.middleware` | Full pipeline + `setup_middlewares()`, rate-limit storage protocol |
+| `nene2.auth` | Bearer / API Key / composite auth, `LocalTokenIssuer`, `make_require_auth()` |
 | `nene2.database` | `SqlAlchemyQueryExecutor`, `SqlAlchemyTransactionManager`, `DatabaseHealthCheck` |
 | `nene2.config` | `AppSettings` (pydantic-settings, reads from env / `.env`) |
 | `nene2.validation` | `ValidationException`, `ValidationError` |
+| `nene2.cache` | `TtlCache[V]` — thread-safe in-memory TTL cache |
+| `nene2.security` | `verify_hmac_signature()` for webhook verification |
 | `nene2.mcp` | `LocalMcpServer`, `HttpxMcpClient` |
 | `nene2.log` | `setup_logging()` (structlog, JSON in production) |
 | `nene2.use_case` | `UseCaseProtocol[I, O]`, `AsyncUseCaseProtocol[I, O]` |
 
+Details: [Framework modules reference](docs/reference/framework-modules.md) · [How-to guides](docs/how-to/)
+
+---
+
+## Versioning
+
+- **`pyproject.toml` `version`** — bumped with each merged FT or feature PR (currently `1.8.97`).
+- **Git tags** (`v1.8.N`) — created on selected releases; may lag behind `pyproject.toml` during rapid FT loops.
+- See [docs/todo/current.md](docs/todo/current.md) for the latest milestone table.
+
 ---
 
 ## PHP NENE2 Correspondence
@@ -197,7 +227,7 @@ uv run pip-audit
 | `readonly class` | `dataclass(frozen=True, slots=True)` |
 | `PHPStan level 8` | `mypy --strict` |
 | `PHP-CS-Fixer` | `ruff format` |
-| `composer check` | `uv run pytest && mypy && ruff check && ruff format --check && pip-audit` |
+| `composer check` | `uv run pytest && mypy && ruff check && ruff format --check && pip-audit --ignore-vuln PYSEC-2025-183` |
 | `ValidationException` | `nene2.validation.ValidationException` |
 | `PaginationQueryParser` | `nene2.http.PaginationQueryParser` |
 | `ErrorHandlerMiddleware` | `nene2.middleware.ErrorHandlerMiddleware` |
@@ -208,4 +238,6 @@ uv run pip-audit
 ## Related
 
 - [NENE2 (PHP)](https://github.com/hideyukiMORI/NENE2) — PHP reference implementation
-- [Documentation](https://hideyukimori.github.io/nene2-python/) — full docs (Diátaxis structure)
+- [Documentation (GitHub Pages)](https://hideyukimori.github.io/nene2-python/) — tutorials, how-to, reference (Diátaxis)
+- [Field Trial INDEX](docs/field-trials/INDEX.md) — FT1–FT219 searchable index
+- [Roadmap](docs/roadmap.md) — current status and planned work

{nene2_python-1.8.66 → nene2_python-1.8.163}/README.md

@@ -6,6 +6,8 @@ A Python reference framework implementing the [NENE2](https://github.com/hideyuk
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
+**Current release**: `v1.8.97` · **466 tests** · CI on Python 3.12 and 3.14
+
 ---
 
 ## Features
@@ -15,11 +17,14 @@ A Python reference framework implementing the [NENE2](https://github.com/hideyuk
 - **`mypy --strict`** — equivalent to PHPStan level 8 type safety
 - **ruff** — lint and format in one tool (replaces flake8, isort, black, bandit)
 - **RFC 9457 Problem Details** — uniform error responses across all endpoints
-- **Bearer Token / API Key auth** — zero-config `LocalTokenVerifier`
+- **Bearer Token / API Key auth** — `LocalTokenVerifier`, `CompositeAuthMiddleware`, dev JWT helpers
 - **MCP support** — expose UseCases as AI agent tools via `LocalMcpServer`
 - **SQLAlchemy Core** — parameterised SQL without ORM overhead
-- **Security middleware** — CSP, X-Frame-Options, rate limiting, request size limit, CORS
+- **Security middleware** — CSP, rate limiting, request size limit, CORS via `setup_middlewares()`
+- **ETag / conditional requests** — `generate_etag()`, `check_not_modified()`, `check_precondition()`
+- **TTL cache & webhooks** — `TtlCache[V]`, `verify_hmac_signature()`
 - **structlog** — structured JSON logging with request ID correlation
+- **219 field trials** — stdlib and framework patterns validated in sandbox apps ([INDEX](docs/field-trials/INDEX.md))
 
 ---
 
@@ -31,31 +36,44 @@ pip install nene2-python
 uv add nene2-python
 ```
 
-Requires Python 3.12+.
+Requires Python 3.12+ (CI also tests 3.14).
 
 ---
 
 ## Quick Start
 
+Use `APIRouter` + `create_app()` at the **end of the file** (see [CLAUDE.md](CLAUDE.md)). Register middlewares with `setup_middlewares()` so 500 responses still get `X-Request-Id` and security headers.
+
 ```python
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI
 from nene2.config import AppSettings
-from nene2.middleware import (
-    ErrorHandlerMiddleware,
-    RequestIdMiddleware,
-    SecurityHeadersMiddleware,
-    ThrottleMiddleware,
-)
-
-cfg = AppSettings()
-app = FastAPI()
-
-app.add_middleware(ErrorHandlerMiddleware, debug=cfg.app_debug)
-app.add_middleware(SecurityHeadersMiddleware)
-app.add_middleware(RequestIdMiddleware)
-app.add_middleware(ThrottleMiddleware, limit=cfg.throttle_limit, window=cfg.throttle_window)
+from nene2.middleware import setup_middlewares
+
+router = APIRouter()
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+def create_app() -> FastAPI:
+    cfg = AppSettings()
+    app = FastAPI(title=cfg.app_name)
+    setup_middlewares(
+        app,
+        debug=cfg.app_debug,
+        throttle_limit=cfg.throttle_limit if cfg.throttle_enabled else None,
+        cors_allowed_origins=cfg.cors_origins if cfg.cors_enabled else None,
+    )
+    app.include_router(router)
+    return app
+
+app = create_app()
 ```
 
+See the full reference app in [`src/example/`](src/example/) (Note / Tag / Comment CRUD, auth, MCP).
+
+---
+
 ### Define a domain
 
 ```python
@@ -92,7 +110,6 @@ class GetNoteUseCase:
 ```python
 from fastapi import APIRouter
 from fastapi.responses import JSONResponse
-from nene2.http import problem_details_response
 
 router = APIRouter(prefix="/notes", tags=["notes"])
 
@@ -102,16 +119,14 @@ async def get_note(note_id: int) -> JSONResponse:
     return JSONResponse({"id": note.id, "title": note.title, "body": note.body})
 ```
 
-See the full working example in [`src/example/`](src/example/).
-
 ---
 
 ## Development Commands
 
 ```bash
 uv sync                         # install dependencies
-uv run pytest                   # run tests (coverage enforced at 80%)
-uv run mypy src/                # type check
+uv run pytest                   # 466 tests, coverage ≥ 80%
+uv run mypy src/                # type check (strict)
 uv run ruff check src/ tests/   # lint
 uv run ruff format src/ tests/  # format
 uv run uvicorn src.example.app:app --reload --port 8080  # dev server
@@ -124,25 +139,39 @@ uv run pytest && \
 uv run mypy src/ && \
 uv run ruff check src/ tests/ && \
 uv run ruff format --check src/ tests/ && \
-uv run pip-audit
+uv run pip-audit --ignore-vuln PYSEC-2025-183
 ```
 
+CI also runs a **90% coverage gate** on `example/*/use_case.py`, `entity.py`, and `async_use_case.py`.
+
 ---
 
 ## Framework Modules
 
 | Module | Purpose |
 |---|---|
-| `nene2.http` | `PaginationQueryParser`, `PaginationResponse`, `problem_details_response()` |
-| `nene2.middleware` | `ErrorHandlerMiddleware`, `SecurityHeadersMiddleware`, `RequestIdMiddleware`, `RequestLoggingMiddleware`, `RequestSizeLimitMiddleware`, `ThrottleMiddleware` |
-| `nene2.auth` | `BearerTokenMiddleware`, `ApiKeyAuthMiddleware`, `LocalTokenVerifier`, `TokenVerifierProtocol` |
+| `nene2.http` | Pagination, Problem Details, health checks, ETag, query helpers, `RequestScopedContext` |
+| `nene2.middleware` | Full pipeline + `setup_middlewares()`, rate-limit storage protocol |
+| `nene2.auth` | Bearer / API Key / composite auth, `LocalTokenIssuer`, `make_require_auth()` |
 | `nene2.database` | `SqlAlchemyQueryExecutor`, `SqlAlchemyTransactionManager`, `DatabaseHealthCheck` |
 | `nene2.config` | `AppSettings` (pydantic-settings, reads from env / `.env`) |
 | `nene2.validation` | `ValidationException`, `ValidationError` |
+| `nene2.cache` | `TtlCache[V]` — thread-safe in-memory TTL cache |
+| `nene2.security` | `verify_hmac_signature()` for webhook verification |
 | `nene2.mcp` | `LocalMcpServer`, `HttpxMcpClient` |
 | `nene2.log` | `setup_logging()` (structlog, JSON in production) |
 | `nene2.use_case` | `UseCaseProtocol[I, O]`, `AsyncUseCaseProtocol[I, O]` |
 
+Details: [Framework modules reference](docs/reference/framework-modules.md) · [How-to guides](docs/how-to/)
+
+---
+
+## Versioning
+
+- **`pyproject.toml` `version`** — bumped with each merged FT or feature PR (currently `1.8.97`).
+- **Git tags** (`v1.8.N`) — created on selected releases; may lag behind `pyproject.toml` during rapid FT loops.
+- See [docs/todo/current.md](docs/todo/current.md) for the latest milestone table.
+
 ---
 
 ## PHP NENE2 Correspondence
@@ -152,7 +181,7 @@ uv run pip-audit
 | `readonly class` | `dataclass(frozen=True, slots=True)` |
 | `PHPStan level 8` | `mypy --strict` |
 | `PHP-CS-Fixer` | `ruff format` |
-| `composer check` | `uv run pytest && mypy && ruff check && ruff format --check && pip-audit` |
+| `composer check` | `uv run pytest && mypy && ruff check && ruff format --check && pip-audit --ignore-vuln PYSEC-2025-183` |
 | `ValidationException` | `nene2.validation.ValidationException` |
 | `PaginationQueryParser` | `nene2.http.PaginationQueryParser` |
 | `ErrorHandlerMiddleware` | `nene2.middleware.ErrorHandlerMiddleware` |
@@ -163,4 +192,6 @@ uv run pip-audit
 ## Related
 
 - [NENE2 (PHP)](https://github.com/hideyukiMORI/NENE2) — PHP reference implementation
-- [Documentation](https://hideyukimori.github.io/nene2-python/) — full docs (Diátaxis structure)
+- [Documentation (GitHub Pages)](https://hideyukimori.github.io/nene2-python/) — tutorials, how-to, reference (Diátaxis)
+- [Field Trial INDEX](docs/field-trials/INDEX.md) — FT1–FT219 searchable index
+- [Roadmap](docs/roadmap.md) — current status and planned work