docs: ドキュメント全体の監査・多角的修正（3ラウンド） (#104)

Round 1 — 致命的な誤りと古いコマンド:
- configure-auth.md (EN/JA): BEARER_TOKENS/API_KEYS をJSON配列形式に修正
  （カンマ区切りはJSONDecodeErrorになる）
- ja/reference/configuration.md: .env例のCORS_ORIGINS/BEARER_TOKENSをJSON配列形式に修正
- design-philosophy.md (EN/JA): 削除済みの `uv run export-openapi` を
  `uv run python src/scripts/export_openapi.py` に修正
- 全言語のテスト数を167+に統一（EN:165+, JA/DE/FR/ZH/PT-BR:135+ がすべて古かった）
- sqlalchemy-repository.md (EN): セクション番号の飛び(4→6)を修正(→5)、末尾の孤立```を削除
- todo/current.md: v0.2.0作業中のTODOリスト(全タスク未完のまま放置)をv1.x完了後の状態に更新

Round 2 — 抜けと不整合:
- new-project.md (EN): BearerTokenMiddleware/ApiKeyAuthMiddleware/CORSMiddlewareのimport文を追加
- configure-auth.md (EN/JA): TokenIssuerProtocol セクションをEN版に追加しJA版と整合
- configure-auth.md (EN/JA): importパスを nene2.auth トップレベルに統一
- architecture.md (EN/JA): schema.pyの説明に「新規プロジェクトはドメイン別ensure_schema」の注記追加
- ja/how-to/run-tests.md: テスト構造のサブディレクトリをEN版に合わせて列挙
- ja/how-to/sqlalchemy-repository.md: Section 5「transactional()を使った原子的マルチライト」を追加
  （EN版には既に存在したがJA版に欠落していた）

Round 3 — JA版の欠けているページ作成:
- docs/ja/how-to/new-project.md: 新規作成（EN版 new-project.md の完全日本語翻訳）

Co-authored-by: hideyukiMORI <info.xion.cc@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

docs/de/tutorials/getting-started.md

@@ -47,7 +47,7 @@ curl http://localhost:8080/notes
 uv run pytest
 ```
 
-Mehr als 135 Tests sollten erfolgreich sein.
+Mehr als 167 Tests sollten erfolgreich sein.
 
 ## Nächste Schritte
 

docs/explanation/architecture.md

@@ -55,7 +55,7 @@ async def create_note(body: CreateNoteBody) -> JSONResponse:
 
 - SQLAlchemy Core (no ORM) with parameterised queries
 - Queries are executed via `SqlAlchemyQueryExecutor`
-- Table schema is managed centrally in `src/example/schema.py`
+- Table schema: the example app uses a central `src/example/schema.py`; for new projects, define `ensure_schema()` in each domain's `sqlalchemy_repository.py` and call each from `create_app()`
 
 ## Middleware stack
 

docs/explanation/design-philosophy.md

@@ -6,7 +6,7 @@ nene2-python shares the same design philosophy as PHP NENE2.
 
 ### API First
 
-The JSON API contract and OpenAPI schema are defined before the database schema. Use `uv run export-openapi` to export a static `openapi.yaml` at any time.
+The JSON API contract and OpenAPI schema are defined before the database schema. Use `uv run python src/scripts/export_openapi.py` to export a static `openapi.yaml` at any time.
 
 ### Thin HTTP layer
 

docs/fr/tutorials/getting-started.md

@@ -47,7 +47,7 @@ curl http://localhost:8080/notes
 uv run pytest
 ```
 
-Plus de 135 tests doivent tous réussir.
+Plus de 167 tests doivent tous réussir.
 
 ## Étapes suivantes
 

docs/how-to/configure-auth.md

@@ -10,7 +10,7 @@ Add to your `.env` file:
 
 ```dotenv
 BEARER_TOKEN_ENABLED=true
-BEARER_TOKENS=token1,token2,token3
+BEARER_TOKENS=["token1","token2","token3"]
 ```
 
 ### Behaviour
@@ -31,7 +31,7 @@ curl -H "Authorization: Bearer token1" http://localhost:8080/notes
 
 ```dotenv
 API_KEY_ENABLED=true
-API_KEYS=key1,key2
+API_KEYS=["key1","key2"]
 ```
 
 ### Behaviour
@@ -64,8 +64,7 @@ client = TestClient(create_app(AppSettings(bearer_token_enabled=False)))
 Implement `TokenVerifierProtocol` and raise `TokenVerificationException` on failure.
 
 ```python
-from nene2.auth import TokenVerificationException
-from nene2.auth.interfaces import TokenVerifierProtocol
+from nene2.auth import TokenVerificationException, TokenVerifierProtocol
 import jwt
 
 class JwtTokenVerifier:
@@ -81,3 +80,19 @@ class JwtTokenVerifier:
 ```
 
 Pass your verifier directly to `BearerTokenMiddleware`.
+
+## Custom TokenIssuer (e.g. JWT)
+
+Implement `TokenIssuerProtocol` to issue tokens (e.g. for a login endpoint).
+
+```python
+from nene2.auth import TokenIssuerProtocol
+import jwt
+
+class JwtTokenIssuer:
+    def __init__(self, secret: str) -> None:
+        self._secret = secret
+
+    def issue(self, claims: dict[str, object]) -> str:
+        return jwt.encode(claims, self._secret, algorithm="HS256")
+```

docs/how-to/new-project.md

@@ -55,6 +55,9 @@ Create `src/app.py`:
 from fastapi import FastAPI
 from fastapi.exceptions import RequestValidationError
 
+from fastapi.middleware.cors import CORSMiddleware
+
+from nene2.auth import ApiKeyAuthMiddleware, BearerTokenMiddleware, LocalTokenVerifier
 from nene2.config import AppSettings
 from nene2.log import setup_logging
 from nene2.middleware import ErrorHandlerMiddleware

docs/how-to/sqlalchemy-repository.md

@@ -232,7 +232,7 @@ def _make_repo() -> SqlAlchemyBookRepository:
 
 ---
 
-## 6. Atomic multi-write operations with `transactional()`
+## 5. Atomic multi-write operations with `transactional()`
 
 When a UseCase needs to write to multiple tables atomically, use `SqlAlchemyTransactionManager.transactional()` together with `_in_tx` repository methods.
 
@@ -344,4 +344,3 @@ class InMemoryTransactionManager(DatabaseTransactionManagerInterface):
 ```
 
 > **Rollback on exception**: `SqlAlchemyTransactionManager.transactional()` uses `engine.begin()` — any exception inside the callback triggers an automatic rollback. Domain exceptions (`AccountNotFoundException`, etc.) propagate normally after rollback.
-```

docs/ja/explanation/architecture.md

@@ -54,7 +54,7 @@ async def create_note(body: CreateNoteBody) -> JSONResponse:
 
 - SQLAlchemy Core（ORM なし）でパラメータ化クエリを実行
 - `SqlAlchemyQueryExecutor` でクエリを抽象化
-- テーブルスキーマは `src/example/schema.py` で一元管理
+- テーブルスキーマ: example アプリは `src/example/schema.py` で一元管理。新規プロジェクトでは各ドメインの `sqlalchemy_repository.py` に `ensure_schema()` を定義し `create_app()` から順番に呼ぶ
 
 ## ミドルウェアスタック
 

docs/ja/explanation/design-philosophy.md

@@ -6,7 +6,7 @@ nene2-python は PHP 版 NENE2 と同一の設計思想を持ちます。
 
 ### API First
 
-JSON API と OpenAPI 契約を中心に据えます。DB 設計より先に API の形を定義し、スキーマを `uv run export-openapi` で生成します。
+JSON API と OpenAPI 契約を中心に据えます。DB 設計より先に API の形を定義し、スキーマを `uv run python src/scripts/export_openapi.py` で生成します。
 
 ### 薄い HTTP 層
 

docs/ja/how-to/configure-auth.md

@@ -11,7 +11,7 @@ nene2-python は Bearer Token 認証と API Key 認証の 2 種類をサポー
 
 ```dotenv
 BEARER_TOKEN_ENABLED=true
-BEARER_TOKENS=token1,token2,token3
+BEARER_TOKENS=["token1","token2","token3"]
 ```
 
 ### 動作
@@ -32,7 +32,7 @@ curl -H "Authorization: Bearer token1" http://localhost:8080/notes
 
 ```dotenv
 API_KEY_ENABLED=true
-API_KEYS=key1,key2
+API_KEYS=["key1","key2"]
 ```
 
 ### 動作
@@ -66,8 +66,7 @@ client = TestClient(create_app(AppSettings(bearer_token_enabled=False)))
 `TokenVerifierProtocol` を実装することで、JWT や外部サービスによる検証を追加できます。
 
 ```python
-from nene2.auth.interfaces import TokenVerifierProtocol
-from nene2.auth.exceptions import TokenVerificationException
+from nene2.auth import TokenVerificationException, TokenVerifierProtocol
 import jwt
 
 class JwtTokenVerifier:
@@ -89,7 +88,7 @@ class JwtTokenVerifier:
 `TokenIssuerProtocol` を実装して、JWT などのトークンを発行できます。
 
 ```python
-from nene2.auth.interfaces import TokenIssuerProtocol
+from nene2.auth import TokenIssuerProtocol
 import jwt
 
 class JwtTokenIssuer: