@joymerrevent/porters-connect 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -5,6 +5,115 @@
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-09-23
+
+**読み取りの値の検証を 1 つ増やし、使い方ドキュメントを組み直した版**です。破壊的変更はありませんが、
+**宣言が実際の項目と合っていないと、これまで通っていた読み取りがエラーになることがあります**（下の Changed）。
+
+### Changed
+
+- **数値でない文字列を `Number` として読まなくなりました**。`Number` / `System[Id]` の項目と
+  `Link` のスカラ形（Contact の ID）に数値として読めない値が来ると、`PortersResourceError`
+  （`category: "validation"`・項目名つき）で失敗します。これまでは `Number("社内候補")` の結果＝**`NaN`** が
+  黙って読み取り値に入り、`typeof === "number"` と `null` 判定の両方を通り、そのまま `update` に戻すと
+  `<Alias>NaN</Alias>` を送っていました。
+
+  ```text
+  U_score: declared Number, but "社内候補" is not a PORTERS Number value
+  ```
+
+  - 起きるのは**宣言が違うとき**です（テキストの項目を `f.number()` と宣言した、など）。PORTERS が
+    Number 項目に数値以外を返す書式は出典にありません。日時（`f.date()` 等）が 0.15.0 から同じ形で
+    エラーになるのと揃えました。
+  - 数値として読める値（`"87"` / `"-1.25"` / 前後の空白）と空（`null`）は変わりません。
+  - 書き込み側は変えていません（`NaN` を渡す JS コードはこれまでどおりそのまま送られます）。
+  - 上げる前に宣言を確かめるなら、これまでどおり `verifyFields` です。
+
+- **使い方ドキュメント（`docs/usage/`）を 7 章に組み直しました**。導入／主題別／クライアント／リソース別／
+  関数／実践例／リファレンスの順で、目次（`docs/usage/index.md`）から章を辿ります。
+  - **リソース別**は 18 種に 1 ページずつで、どのページも「呼べるメソッド → 固有の注意 → 新規作成の必須項目 →
+    項目と型」の同じ順に並びます。
+  - **クライアント**（`PortersClient` の構築オプション・`porters.auth` の 6 メソッド・`tenant(id)` のスコープ）と
+    **関数**（宣言と突合・上限と接続・値の変換）の章を新設し、導入と主題別に散らばっていた一覧をまとめました。
+  - **主題別**（検索・書き込み・認証・カスタム項目・上限など）は「まず知ること → 使い方 → 細かい規則」の順に
+    書き直し、言い回しを平易にしています。内容の食い違い（`Promise` を返さない関数の一覧の漏れなど）も直しました。
+
+### Fixed
+
+- **単件の `create` / `update` が、`of()` で指定済みの項目（Phase の `Resource`）を渡されたとき、
+  同期 throw していました**。`Promise` を返すほかの公開メソッドと同じく、reject で届くようにしました。
+  入力型が `Resource` を受け付けないので、TypeScript から普通に書く限り起きません（`as any` を通した場合と
+  JavaScript から呼んだ場合だけ）。例外の種類・`message`・`category` は変わりません。
+
+## [0.21.0] - 2026-09-21
+
+**カスタム項目の宣言を、partition を束ねる `tenant(id)` で受け取るようにした版**です。
+**破壊的変更を 1 つ**含みます（コンストラクタの `fields` の廃止。移行は 1 対 1）。あわせて、
+利用者が読むもの（公開 JSDoc・使い方ドキュメント・エラーの `hint`）から、保守者向けの識別子と
+廃止済みのオプション名を取り除きました。
+
+### Changed
+
+- **（破壊的）カスタム項目の宣言は `tenant(id, { fields })` で受け取るようになりました**（[ADR-0087][adr87]）。
+  `PortersClientOptions` から `fields` が無くなり、`PortersClient` / `PortersClientOptions` は
+  型引数を取らなくなります。
+
+  カスタム項目（`U_` / `A_`）は **partition（Company DB）ごとのもの**です — 出典の各リソース記事が
+  「テナント毎に異なる」としています。これまで宣言は client に 1 つしか持てず、項目構成の違う
+  テナントを同じ client で扱うと、**別テナントの宣言が黙って適用される**形でした（ずれは読み取り時の
+  `validation` エラーで見えますが〔0.15.0〕、どのテナントの宣言を当てたのかをライブラリは知らないので、
+  正しい宣言に取り替える手掛かりがありません）。partition を束ねる `tenant(id)` が、
+  その partition の項目の形も束ねます。
+
+  ```ts
+  // 変更前
+  const porters = new PortersClient({ hostname, appId, appSecret, fields });
+  const t = porters.tenant(123);
+
+  // 変更後
+  const porters = new PortersClient({ hostname, appId, appSecret });
+  const t = porters.tenant(123, { fields });
+  ```
+
+  - **移行は 1 対 1**です。コンストラクタの `fields` を `tenant()` の第 2 引数に移すだけで、
+    `t` 以降のコードは変わりません。`tenant(id)`（第 2 引数なし）はこれまでどおり標準項目だけです。
+  - **項目構成の違うテナント群を 1 つの client（1 つのトークン）で扱えます**。
+    `porters.tenant(1, { fields: a })` と `porters.tenant(2, { fields: b })` は、それぞれの宣言で
+    読み書きします。client を分けるのは**トークンを分けたいとき**だけになりました。
+  - `A_` を App 共通、`U_` をテナント固有にしたい場合は、共通部分を関数にして各テナントの宣言に
+    spread します（ライブラリは `A_` と `U_` を区別しません）。書き方は
+    [カスタム項目ガイド][howto-custom-fields]にあります。
+  - **コンストラクタに `fields` が残っていると、構築時に `PortersConfigError`**（`category: "config"`）で
+    止まります。`hint` が `tenant(id, { fields })` を指します。型でも弾きます（`fields` は `never`）。
+    黙って無視すると宣言が丸ごと捨てられ、カスタム項目が型から消えたまま動いてしまうためです。
+    `fields: undefined` は未指定と同じ扱いです。
+  - 型を書くときは、`PortersClient<typeof fields>` / `PortersClientOptions<typeof fields>` が
+    **コンパイルエラー**になります。スコープを受ける関数は `TenantScope<typeof fields>`（これまでどおり）、
+    `tenant()` の引数を切り出すなら新設の `TenantOptions<typeof fields>` で書きます。
+    `ReturnType<typeof porters.tenant>` で受けていた関数は、`tenant` がジェネリックになったため
+    **広い型（`TenantScope<DeclaredCatalogs>`）**に落ち、カスタム項目が型から消えます（使う箇所で
+    コンパイルエラーになります）。`TenantScope<typeof fields>` に書き換えてください。
+  - `generateFieldDecls` / `verifyFields` / `readCustomCatalog` は変わりません（もともと `tenant(id)`
+    スコープを取ります）。
+
+- **公開 API の JSDoc（IDE のホバーと API リファレンスに出る説明文）から、ADR 番号やレビュー指摘番号
+  などの保守者向けの識別子を取り除きました**。利用者には意味を持たない情報で、根拠は実装コメントへ
+  移しています。型・メソッドの意味や挙動は変わりません（説明文だけの変更）。同じ識別子が
+  生成物に戻らないよう、API リファレンスと配布する型定義（`dist/index.d.ts`）を検査するようにしました。
+
+- **利用者向けドキュメント（`docs/usage/` と README）の本文からも、同じ識別子と設計文書へのリンクを
+  取り除きました**。説明の内容は変わりません。文末の `（ADR-0059）` のような表記が消え、設計文書に
+  委ねていた数か所は本文に書き足しています。PORTERS ヘルプセンターの再取得手順（保守者向け）は
+  `CONTRIBUTING.md` へ移しました。あわせて、リリース前に使い方ドキュメント全体を実装と突き合わせ、
+  実装と食い違っていた記述（権限付与未実施のときのエラーの系統、`tenant(id, { fields })` 以前の
+  「client を分ける」案内など）を直しています。
+
+### Fixed
+
+- **PORTERS 以外が返した HTTP エラー（`category: "config"`）の `hint`** が、0.18.0 で廃止した
+  オプション名 `host` を案内していました。現在の `hostname` / `port` / `scheme` を指すように直しました。
+  挙動は変わりません（説明文だけの変更）。
+
 ## [0.20.1] - 2026-09-21
 
 **定期レビュー（0.20.0 直後）で見つけた 1 件を塞いだ版**です。破壊的変更はありません。
@@ -204,7 +313,7 @@ reference にも実装にも無く、**時分型**（2026/08・PORTERS 9.3.0）
 
 PORTERS が `resource=` を **URL パラメータで必須**に要求するエンドポイントは 3 つ（Field / Phase /
 Attachment）あるのに、受け口の形が 3 つとも違っていました。**パラメータのリソースは `of(name)` で
-束ね、項目の値は宣言した Data Type どおり（数値）**という線を引き、3 本とも `of()` に揃えています。
+束ね、項目の値は宣言した Data Type どおり（数値）** という線を引き、3 本とも `of()` に揃えています。
 
 ### Added
 
@@ -890,7 +999,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
     **呼び出し側の書き味は変わりません**。
   - **App レベルのものは `porters` 側に残ります**（いずれも `partition` を取りません）—
     `porters.auth.*`（OAuth）と `porters.partition.search()`（partition の発見）。
-  - 理由: `partition` 未設定のクライアントは**`partition=0`** を全リクエストに載せていました。
+  - 理由: `partition` 未設定のクライアントは **`partition=0`** を全リクエストに載せていました。
     `0` は PORTERS のドキュメントに存在しない値で、由来は最初の PoC の穴埋めです。実際には
     Result Code **404** を招くため、**設定漏れが「サーバーが 404 を返す」形に化け**ていました。
     `tenant(id)` を唯一の経路にすることで、**「partition を束ね忘れたクライアント」という状態が
@@ -1177,7 +1286,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 - **エラー対処ガイド**: [docs/howto/handle-failures.md][guide]（症状別早見表＋2 系統のコード対応表）。
 - **配布**: ESM / Node.js 18+ / 型定義同梱 / MIT。`X-P-ConnectAPI-Version: 2` を既定送信（PORTERS 8.x・9.x 想定）。
 
-[guide]: docs/usage/howto/handle-failures.md
+[guide]: docs/usage/topics/errors.md
 [adr44]: docs/adr/0044-http-status-handling.md
 [adr45]: docs/adr/0045-write-response-root-code.md
 [adr46]: docs/adr/0046-guard-error-contract.md
@@ -1186,12 +1295,12 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [adr50]: docs/adr/0050-auth-http-status-handling.md
 [adr51]: docs/adr/0051-read-envelope-identification.md
 [adr47]: docs/adr/0047-access-point-scheme.md
-[oauth-guide]: docs/usage/howto/authenticate.md
+[oauth-guide]: docs/usage/topics/auth.md
 [adr19]: docs/adr/0019-static-resource-types.md
 [adr20]: docs/adr/0020-read-field-default.md
 [adr35]: docs/adr/0035-usage-documentation-structure.md
-[custom-fields-guide]: docs/usage/howto/custom-fields.md
-[read-query-guide]: docs/usage/howto/search-records.md
+[custom-fields-guide]: docs/usage/topics/custom-fields.md
+[read-query-guide]: docs/usage/topics/query.md
 [adr55]: docs/adr/0055-partition-binding-guard.md
 [adr56]: docs/adr/0056-deleted-flag-typing.md
 [adr57]: docs/adr/0057-itemstate-existing-explicit.md
@@ -1204,7 +1313,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [rv22]: docs/reviews/rv/0022-ratelimit-create-no-retry.md
 [rv32]: docs/reviews/rv/0032-searchall-query-mutation.md
 [rv44]: docs/reviews/rv/0044-fields-excluded-from-coverage.md
-[write-constraints]: docs/usage/concepts/limits.md
+[write-constraints]: docs/usage/topics/limits.md
 [adr68]: docs/adr/0068-api-reference-tooling.md
 [adr69]: docs/adr/0069-tenant-field-catalog-tooling.md
 [adr73]: docs/adr/0073-throttle-sharing.md
@@ -1217,14 +1326,16 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [adr80]: docs/adr/0080-resource-parameter-binding.md
 [adr81]: docs/adr/0081-attachment-read-parameters.md
 [adr82]: docs/adr/0082-module-format-and-node-baseline.md
-[limits]: docs/usage/concepts/limits.md
-[failures]: docs/usage/howto/handle-failures.md
+[limits]: docs/usage/topics/limits.md
+[failures]: docs/usage/topics/errors.md
 [adr85]: docs/adr/0085-option-alias-validation.md
 [lv]: docs/live-verification.md
 [ref]: docs/usage/reference/README.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.1...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.21.0...v0.22.0
+[0.21.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.0...v0.20.1
 [0.20.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.19.1...v0.20.0
 [0.19.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.19.0...v0.19.1
@@ -1260,4 +1371,6 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [gh5]: https://github.com/advisories/GHSA-7w5x-hrqm-74c2
 [fastcheck]: https://github.com/dubzzz/fast-check
 [adr86]: docs/adr/0086-time-of-day-fields.md
+[adr87]: docs/adr/0087-tenant-scoped-field-declarations.md
+[howto-custom-fields]: docs/usage/topics/custom-fields.md
 [ref-department]: docs/usage/reference/resource-api/resources/department.md

package/README.md

@@ -10,36 +10,35 @@ PORTERS Connect API（旧 HRBC）を **TypeScript から型安全・簡単に**
 > 利用には **PORTERS の契約 ＋ Connect API オプション契約**が必要です（ホスト名・App ID/Secret は契約時に通知されます）。
 
 XML レスポンスを型付きオブジェクトに変換し、独自仕様の OAuth・レート制御・エラー整理を内側に隠します。
-**薄く・堅く**を方針に、フェイルセーフ（壊れたときに安全側へ倒れる）設計です。
 
 ---
 
 ## 特徴
 
-- **型安全**：リソース・項目の値を型で表現。`any` を撒きません。
-- **XML を外に出さない**：返り値は型付きオブジェクト、入力も素直な JS の値。
-- **独自 OAuth を透過**：`code_direct` によるトークン取得・キャッシュ・更新を自動化。
-- **上限内に自制する**：スロットリング・リトライ（指数バックオフ）・リクエストサイズガード内蔵。
+- **型安全**：リソース・項目の値を型で表現。`any` を使いません。
+- **XML を外に出さない**：返り値は型付きオブジェクト、入力もふつうの JS の値。
+- **独自 OAuth を意識させない**：`code_direct` によるトークン取得・キャッシュ・更新を自動化。
+- **上限を守る**：スロットリング・リトライ（指数バックオフ）・リクエストの長さの検査を内蔵。
 - **日時は ISO 8601（UTC）に正規化**。業務タイムゾーン変換はしません（利用側の責務）。
-- **PORTERS の全リソースに対応**：データ系 13 種 ＋ Phase ＋ マスタ Read 5 種。
+- **PORTERS の全リソースに対応**：データ系 13 種（Phase・Attachment を含む）＋ マスタ系 5 種（読み取り専用）。
 
 ## 前提
 
-繋ぐ前に、**PORTERS 側で 4 つ**が要ります。揃っていないと 1 行も動きません。
+繋ぐ前に、**PORTERS 側で 4 つ**が要ります。揃っていないと PORTERS を呼べません。
 
 1. **PORTERS 契約 ＋ Connect API オプション契約**（オプションは別契約）。
 2. **API アプリの登録**。ここで Redirect URL を決め、**ホスト名・App ID・App Secret** が
-   通知されます（いずれも機密情報・ハードコード禁止）。
+   通知されます（いずれも機密情報なので、コードに直接書かず環境変数で渡します）。
 3. **初回のみブラウザで権限付与**（人手・Company DB ごとに 1 回）。以降はライブラリが
    `code_direct`（サーバ間）で無人運用します。
 4. **付与するスコープ**の決定（リソース別に `_r` / `_w`。Read でも複数要ることがあります）。
 
 揃えかたは[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]に
-あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です。配るのは ESM 1 本ですが、
-CJS からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
+あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です。ビルド済みの JavaScript ファイルは ESM（`import`）の 1 つですが、
+CJS（`require`）からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
 
 契約や権限付与を**待っている間**も、PORTERS に繋がずにコードとテストは書けます
-（[契約なしでテストを書きたい][test-without-contract]）。
+（[契約なしでテストする][test-without-contract]）。
 
 ## インストール
 
@@ -55,12 +54,12 @@ npm i @joymerrevent/porters-connect
 import { PortersClient } from "@joymerrevent/porters-connect";
 
 const porters = new PortersClient({
-  hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。ハードコード禁止
+  hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。コードに直接書かず環境変数で渡す
   appId: process.env.PORTERS_APP_ID ?? "",
   appSecret: process.env.PORTERS_APP_SECRET ?? "",
 });
 
-// partition（Company DB）は tenant で一度だけ束ねる。**単一テナントでもこの形**
+// partition（Company DB）は tenant(id) で指定する（既定の Partition は無い）。単一テナントでも同じ書き方
 const t = porters.tenant(456);
 
 const page = await t.candidate.search({
@@ -73,7 +72,7 @@ const page = await t.candidate.search({
 console.log(page.total, page.items[0]?.P_Name);
 ```
 
-続きは[入門][s-prereq]（6 ページ）へ。準備・認証・読み取り・書き込み・本番に出す前の確認まで順に進みます。
+続きは[導入][s-prereq]（6 ページ）へ。準備・認証・読み取り・書き込み・本番に出す前の確認まで順に進みます。
 
 ## リソースと操作
 
@@ -87,46 +86,51 @@ console.log(page.total, page.items[0]?.P_Name);
 | `t.opportunity` | 商談管理       | `t.phase`      | フェーズ履歴 |
 | `t.activity`    | アクティビティ |                |              |
 
-マスタ Read は `porters.partition` / `t.user` / `t.department` / `t.field` / `t.option` の 5 種（読み取り専用）。
+マスタ系は `porters.partition` / `t.user` / `t.department` / `t.field` / `t.option` の 5 種（読み取り専用）。
 
-**どのメソッドが呼べるかはリソースごとに違います**（`searchAll` が無いもの、先に `of()` で
-束ねるものがあります）。一覧は[リソースと操作][docs-resources]、引数・戻り値・項目の一覧は
-[API リファレンス][api-ref]が正典です。
+**どのメソッドが呼べるかはリソースごとに違います**（`searchAll` が無いもの、先に `of("candidate")` のように
+対象リソースを指定するもの（Field・Phase・Attachment）があります）。一覧は[リソースと操作][docs-resources]、引数・戻り値・項目の一覧は
+[API リファレンス][api-ref]が正確な定義です。
 
 ## ドキュメント
 
-**[docs/usage][docs-index] が目次**です。4 層に分かれています。
+**[docs/usage][docs-index] が目次**です。7 つの章に分かれていて、順に読むのは導入だけです。
 
-| 層               | 何が書いてあるか                                                                   |
-| ---------------- | ---------------------------------------------------------------------------------- |
-| **入門**         | 順に読む 6 ページ。準備 → 導入 → 認証と疎通 → 読み → 書き → 本番前                 |
-| **目的別**       | 「〜したい」から引く 9 ページ（検索・一括書き込み・添付・同期バッチ・テスト ほか） |
-| **考え方**       | PORTERS 固有の前提（Partition ／ alias と Data Type ／ UTC ／ 削除が無い ／ 上限） |
-| **リファレンス** | [公開 API の全記号][api-ref]（JSDoc から生成）と [PORTERS API の事実][ref]         |
+| 章               | 何が書いてあるか                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| **導入**         | 順に読む 6 ページ。準備 → インストール → 認証と疎通 → 読み → 書き → 本番前                  |
+| **主題別**       | 認証・検索・書き込み・カスタム項目・上限……の 11 主題を、考え方から細かい規則まで 1 ページで |
+| **クライアント** | `PortersClient`・`auth`・`tenant(id)` のスコープ。構築オプションと呼べるメソッド            |
+| **リソース別**   | 18 リソースを 1 ページずつ。呼べるメソッド・固有の注意・必須項目・型                        |
+| **関数**         | `import` して呼ぶ関数を用途別に。宣言と突合・上限と接続・値の変換                           |
+| **実践例**       | 毎日の差分同期・複数テナントなど、用途に沿った組み立て                                      |
+| **リファレンス** | [公開 API リファレンス][api-ref]（JSDoc から生成）と [PORTERS API の事実][ref]              |
+
+目次の末尾に「〜したい → 読む場所」の索引表があります。
 
 ## PORTERS 固有の注意
 
 このライブラリを使ううえで、**PORTERS 側の前提**として先に知っておくと迷いません。詳しくは
-それぞれの「考え方」ページにあります。
+それぞれの主題ページの「まず知ること」にあります。
 
-- **削除 API が存在しない**。`delete()` は型の上でも生やしていません（[削除 API が無いということ][c-no-delete]）。
-- **日時は UTC 前提**。ISO 8601（`…Z`）で入出力し、JST 等への変換はしません（[日時は UTC][c-datetime]）。
-- **データは Partition に分かれる**。`tenant(id)` で毎回束ねます（[Partition とテナント][c-partition]）。
+- **削除 API が存在しない**。`delete()` は型の上でも用意していません（[削除と削除済みデータ][c-no-delete]）。
+- **日時は UTC 前提**。ISO 8601（`…Z`）で入出力し、JST 等への変換はしません（[日時と時分型][c-datetime]）。
+- **データは Partition に分かれる**。`tenant(id)` で毎回指定します（[Partition とテナントスコープ][c-partition]）。
 - **上限がある**。リクエスト長 約 15000 文字・1 リクエスト 200 件・1 分あたり Read 2000 / Write 500 は
-  ライブラリが自制しますが、**月 15 万アクセスは契約条件**で利用側の運用責務です（[上限][c-limits]）。
+  ライブラリが守りますが、**月 15 万アクセスは契約条件**で利用側の運用責務です（[上限とレート][c-limits]）。
 - **ホスト名は非公開**。`PORTERS_HOST` で受け取り、ハードコードしません。
 
 ## 対応バージョン
 
-- **契約は Connect API Version 2**：`X-P-ConnectAPI-Version: 2` を既定送信し、**v2 を動作の前提**とします（担当者型・部署型 Link 等は v2 必須）。互換性はこの **API version** で明示します。
-- **PORTERS 製品 8.x / 9.x は参考**：v2 が提供される製品世代です（個別マイナーの動作保証はしません）。**正典は [PORTERS API の事実][ref]**（実 API ドキュメントに接地）。
+- **互換性の基準は Connect API Version 2**：`X-P-ConnectAPI-Version: 2` を既定で送信し、**v2 を動作の前提**とします（担当者型・部署型の参照項目（Link）などは v2 が必要）。互換性はこの **API version** で明示します。
+- **PORTERS 製品 8.x / 9.x は参考**：v2 が提供される製品世代です（個別マイナーの動作保証はしません）。**正しい情報の出どころは [PORTERS API の事実][ref]**（PORTERS の公式ドキュメントに基づく）。
 
 ## リンク
 
-**この README は「最短で動かす」ところまで**です。網羅は目次側が担当します（[ADR-0070][adr70]）。
+**この README は「最短で動かす」ところまで**です。全体は目次から読めます<!-- 根拠: ADR-0070 -->。
 
-- 利用者向け：[docs/usage][docs-index]（目次）／[公開 API の全記号][api-ref]／[PORTERS API の事実][ref]
-- 開発・保守：[docs/README.md][docs-readme]（ADR・基本設計・ロードマップ・台帳への入口）
+- 利用者向け：[docs/usage][docs-index]（目次）／[公開 API リファレンス][api-ref]／[PORTERS API の事実][ref]
+- 開発・保守：[docs/README.md][docs-readme]（ADR（設計判断の記録）・基本設計・ロードマップ・台帳）
 - 提供元：[Joymerrevent][joymerrevent]
 
 ## コントリビュート / セキュリティ
@@ -156,16 +160,15 @@ console.log(page.total, page.items[0]?.P_Name);
 [coc]: ./CODE_OF_CONDUCT.md
 [issues]: https://github.com/Joymerrevent/porters-connect/issues
 [api-ref]: docs/usage/api/index.md
-[c-datetime]: docs/usage/concepts/datetime.md
-[c-limits]: docs/usage/concepts/limits.md
-[c-no-delete]: docs/usage/concepts/no-delete.md
-[c-partition]: docs/usage/concepts/partition.md
+[c-datetime]: docs/usage/topics/datetime.md
+[c-limits]: docs/usage/topics/limits.md
+[c-no-delete]: docs/usage/topics/deleted.md
+[c-partition]: docs/usage/topics/tenant.md
 [s-auth]: docs/usage/start/authenticate.md
 [s-cjs]: docs/usage/start/install.md#cjs-から-require-する
 [s-prereq]: docs/usage/start/prerequisites.md
-[test-without-contract]: docs/usage/howto/test-without-contract.md
+[test-without-contract]: docs/usage/topics/testing.md
 [docs-index]: docs/usage/index.md
-[docs-resources]: docs/usage/index.md#リソースと操作
-[adr70]: ./docs/adr/0070-usage-documentation-architecture.md
+[docs-resources]: docs/usage/resources/README.md
 [docs-readme]: ./docs/README.md
 [ref]: docs/usage/reference/README.md