@geekbeer/minion 4.2.0 → 4.3.3

package/rules/core.md

@@ -514,6 +514,68 @@ cp /tmp/report.pdf ~/files/reports/2026-04/report.pdf
 - テキスト成果物 → ローカルメモリ (`POST /api/memory`) に保存
 - バイナリファイル → `~/files/` に保存
 
+## Accounting Operations (会計操作, v4.3.0〜)
+
+会計データは法的責任を伴うため、**accountant ロールを付与されたミニオンのみ** 操作可能。
+
+### アクセス要件
+
+- 対象 workspace 内の **いずれかのプロジェクト** で `accountant` ロールを持っていること
+- workspace で `experimental_accounting` feature flag が ON であること
+- 不在の場合は 403 `code: 'accountant_role_required'` / `'feature_disabled'` が返る
+
+### API
+
+エンドポイントは `/api/minion/workspaces/:id/accounting/*`。詳細は `~/.minion/docs/api-reference.md` の「Accounting」セクションを参照。
+
+主なリソース:
+- **Books / Periods / Reports** — 帳簿メタ、決算期、試算表 / B/S / P/L (照会のみ)
+- **Accounts** — 勘定科目の照会 (GET) と追加 (POST) のみ。rename / アーカイブ / 削除は人間専用
+- **Counterparties** — 取引先マスタの照会・追加・更新 (GET / POST / PATCH。`is_archived` でアーカイブ可)
+- **Journal Entries** — 仕訳の作成 (POST) と AI 生成仕訳の更新 (PATCH)
+- **Receipts** — レシート一覧 / ダウンロード
+- **Expense Reimbursements** — 立替経費の登録
+- **Tax Calculations** — 法人税計算ウィザード (別表四相当の加減算 + 6 税目別税率入力 + 仕訳生成準備)
+
+### 守るべきルール
+
+1. **仕訳は `source='ai_generated'` で自動記録される** — ミニオン経由で作成した仕訳は HQ UI で 🤖 バッジ付きで表示される。人間がレビューしてから承認する前提で動くこと。
+2. **人間作成仕訳 (`source='manual'` / `'import'`) は更新できない** — PATCH すると 409 `code: 'human_owned_entry'`。修正が必要なら人間に依頼する。
+3. **税率はユーザー責任で入力する** — 法人税計算ウィザードの税率欄は国税庁・自治体サイトで最新値を調査して入力すること。本ツールは税率テーブルを持たない。
+
+### 人間専用操作 (ミニオンから提供されない API)
+
+以下はデータの根幹に影響するため、ミニオンが自律実行することを禁止している。
+ミニオンは **threads で `@user` メンション + 計算 ID / 期 ID をリンクして人間に依頼** すること。
+
+| 操作 | 依頼すべき相手 / 方法 |
+|------|---------------------|
+| 決算期の `close` / `reopen` / 期首残高設定 | HQ ダッシュボード `/accounting/periods` から人間が実行 |
+| 法人税計算の `finalize` / `journalize` / `reopen` | `/accounting/tax-calculations/:id` のウィザード末尾ボタン |
+| 仕訳・科目・取引先・税計算の `DELETE` | HQ UI 各リスト画面 |
+| 勘定科目の rename / アーカイブ (`PATCH`) | `/accounting/accounts` から人間が実行 (ミニオンは POST のみ) |
+| 立替経費の `settle` / `bulk-settle` | `/accounting/reimbursements` の精算ボタン |
+| レシートと仕訳の `attach` / `detach` | HQ UI で人間が判断 |
+
+依頼スレッドの body 例:
+```bash
+curl -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  http://localhost:8080/api/threads \
+  -d '{
+    "thread_type": "help",
+    "mentions": ["user"],
+    "title": "法人税計算 FY3 の finalize お願いします",
+    "content": "計算ID XXXX の入力が完了しました。HQダッシュボードでレビュー後、Finalize → Journalize ボタンを押してください。",
+    "context": { "accounting_action": "tax_finalize", "calculation_id": "XXXX" }
+  }'
+```
+
+### 監査と可視化
+
+ミニオン書き込みは以下で記録・可視化される:
+- DB: `created_by_minion_id` / `updated_by_minion_id` 列 (主要 7 テーブル)
+- HQ UI: 仕訳一覧 / 取引先 / 立替経費 / 法人税計算ウィザードの各項目に 🤖 バッジ表示
+
 ## Documentation
 
 API仕様やタスク手順の詳細は以下を参照:

package/skills/accounting-bookkeeping/SKILL.md

@@ -1,17 +1,26 @@
 ---
 name: accounting-bookkeeping
-description: 会計帳簿の記帳・立替経費の処理・補助元帳の照会を行うワークフロー。使用タイミング：(1) 取引を仕訳として記録する時、(2) 役員・従業員の立替経費を記帳・精算する時、(3) 取引先別の残高を確認する時。accountantロールのミニオンが主に使用する。
+description: 会計帳簿の記帳・立替経費の処理・補助元帳の照会・財務諸表の照会・法人税計算の補助を行うワークフロー。使用タイミング：(1) 取引を仕訳として記録する時、(2) 役員・従業員の立替経費を記帳する時、(3) 取引先別の残高を確認する時、(4) 試算表・B/S・P/L を取得して報告する時、(5) 法人税計算ウィザードに入力する時。accountantロールのミニオンが主に使用する。
 ---
 
 # Accounting Bookkeeping
 
 会計帳簿(HQ Accounting API)を操作するためのスキル。複式簿記の整合性を保ちながら、AI(ミニオン)が安全に記帳できるよう設計されている。
 
-## 前提
+## 前提・アクセス要件
 
-- ワークスペースで experimental_accounting feature flag が有効になっていること
-- HQ API は `$HQ_URL/api/accounting/*` で利用可能(authentication は `Authorization: Bearer $API_TOKEN`)
-- 1ワークスペース1帳簿の前提。`GET /books` で帳簿を取得し、勘定科目テンプレートはデフォルトで投入済み
+このスキルが叩くのは **ミニオン専用の会計 API** (`$HQ_URL/api/minion/workspaces/:id/accounting/*`)。
+人間用の `/api/accounting/*` (Supabase セッション認証) とは別系統で、**ミニオンは必ずこちらを使う**こと。
+
+- 認証は `Authorization: Bearer $API_TOKEN`。`:id` は対象 **ワークスペース ID**(パスに含める)
+- 対象 workspace 内の **いずれかのプロジェクト**で `accountant` ロールを持っていること
+  (持たない場合は 403 `code: 'accountant_role_required'`)
+- workspace で `experimental_accounting` feature flag が ON であること
+  (OFF なら 403 `code: 'feature_disabled'`)
+- 1ワークスペース1帳簿の前提。`GET .../books` で帳簿を取得し、勘定科目テンプレートはデフォルトで投入済み
+- 書き込みは `created_by_minion_id` / `updated_by_minion_id` に呼び出し元ミニオン ID が記録され、HQ UI で 🤖 バッジ表示される。仕訳の `source` は常に `'ai_generated'`
+
+API 全体のエンドポイント表は `~/.minion/docs/api-reference.md` の「Accounting」セクションを参照。
 
 ## 語彙
 
@@ -26,12 +35,14 @@ description: 会計帳簿の記帳・立替経費の処理・補助元帳の照
 
 ## 典型フロー
 
+> 以下のパスはすべて `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+
 ### A) 通常取引の記帳
 
 ```
-1. GET /api/accounting/accounts で勘定科目一覧取得
+1. GET /accounts で勘定科目一覧取得
 2. 入金/出金口座(is_wallet=true)と相手勘定(費用 or 収益)を特定
-3. POST /api/accounting/entries でシンプル仕訳を作成
+3. POST /entries でシンプル仕訳を作成
    body: { entry_type: 'expense'|'income', entry_date, amount, wallet_account_id, category_account_id, description }
 ```
 
@@ -41,37 +52,82 @@ description: 会計帳簿の記帳・立替経費の処理・補助元帳の照
 
 ```
 1. 立替者(役員/従業員)の counterparty を確認
-   - GET /api/accounting/counterparties?q=<name>&kind=director,employee
-   - 見つからなければ POST /api/accounting/counterparties で作成
+   - GET /counterparties?kind=director,employee
+   - 見つからなければ POST /counterparties で作成
    - default_payable_account_id が未設定なら PATCH で先に設定する
-2. POST /api/accounting/expense-reimbursements で記帳
+2. POST /reimbursements で記帳
    body: { paid_by_counterparty_id, occurred_on, amount, expense_account_id, description }
    → 内部で「(借)費用 / (貸)立替者の負債科目」の仕訳が自動生成される
-3. レシートがあれば事前に POST /api/accounting/receipts でアップロードし、receipt_ids を渡す
+3. レシートがあれば事前に GET /receipts で対象を確認 (アップロードと仕訳への attach は人間が HQ UI で行う)
 ```
 
 詳細: `references/api-expense-reimbursement.md`
 
-### C) 立替経費の精算
+### B') レシートの照会・OCR
 
 ```
-1. GET /api/accounting/expense-reimbursements?settled=false で未精算リスト取得
-2. POST /api/accounting/expense-reimbursements/<id>/settle で精算
-   body: { settled_on, wallet_account_id }
-   → 内部で「(借)立替者の負債科目 / (貸)現金or預金」の仕訳が自動生成される
+GET /receipts?attached=false        → 未処理(未添付)レシート一覧
+GET /receipts/:receiptId/download   → 60秒有効な signed URL を取得し画像/PDFを読み取り (OCR)
 ```
 
-部分精算は非対応。全額精算のみ。
+読み取った内容から仕訳/立替を作成する。アップロードと仕訳への attach/detach は人間専用。
+詳細: `references/api-receipts.md`
+
+### C) 立替経費の精算 — **人間専用**
+
+精算 (`settle` / `bulk-settle`) は実際の出金を伴うため**ミニオンからは実行できない**。
+未精算リストを `GET /reimbursements?status=unsettled` で把握し、精算が必要な分は
+`POST /api/threads` で `@user` メンションして HQ UI の精算ボタンを依頼すること。
 
 ### D) 補助元帳の照会
 
 ```
-GET /api/accounting/counterparties/<id>/balance
-→ 取引先別の残高(勘定科目ごと)・明細リスト・未精算立替件数を返す
+GET /counterparties/:counterpartyId
+→ 取引先の詳細 + 残高サマリ ({ counterparty, balance: { debit_total, credit_total, net } }) を返す
 ```
 
 詳細: `references/api-counterparties.md`
 
+### E) 財務諸表の照会・報告
+
+```
+GET /reports/trial-balance   → 試算表 + B/S + P/L 一括 (Query: ?from&to&includeZero)
+GET /reports/income-statement → P/L のみ (軽量)
+GET /reports/balance-sheet    → B/S のみ (軽量)
+```
+
+PM やユーザーへの月次報告などで使う。取得した数値は**ノート (`hq note create`)** にまとめて共有するとよい。
+詳細: `references/api-reports-tax.md`
+
+### F) 法人税計算ウィザードの入力補助
+
+`org_type=corporation` / `general_incorporated_association` の帳簿のみ対象 (それ以外は 403 `org_type_ineligible`)。
+ミニオンが触れるのは `draft` 状態のみ。**`finalize` / `journalize` は人間専用**。
+
+```
+1. GET /periods で対象期 (status='open') を選ぶ
+2. POST /tax-calculations で新規作成 (pretax_income は P/L から自動取得)
+3. POST /tax-calculations/:calcId/ensure-accounts で必要4科目を揃える
+4. 国税庁・自治体サイトで最新税率を調査 → PATCH /tax-calculations/:calcId/components/:compId で各税目の tax_rate を入力
+5. 中間納付があれば PATCH /components/:compId で prepaid_amount を入力
+6. 必要なら POST /tax-calculations/:calcId/adjustments で別表四相当の加減算を追加
+7. POST /api/threads で人間に finalize → journalize を依頼
+```
+
+詳細: `references/api-reports-tax.md`
+
+### G) 勘定科目の追加
+
+テンプレートに不足している科目(例: 立替用の「役員借入金」)は追加できる。
+
+```
+POST /accounts
+  body: { name, type: 'asset'|'liability'|'equity'|'revenue'|'expense', code?, is_wallet?, sort_order? }
+```
+
+**科目の rename / アーカイブ / 削除はミニオンからは実行できない**(人間専用)。
+不要・誤った科目の整理が必要な場合は `POST /api/threads` で人間に HQ UI 操作を依頼すること。
+
 ## エラーレスポンスの読み方
 
 会計APIは AI 向けに以下の構造でエラーを返す:
@@ -80,7 +136,7 @@ GET /api/accounting/counterparties/<id>/balance
 {
   "error": "missing_default_payable_account",
   "message": "取引先「山田太郎」に立替用の貸方科目が未設定です",
-  "next_action": "PATCH /api/accounting/counterparties/<id> で default_payable_account_id を設定してください...",
+  "next_action": "PATCH /counterparties/<id> で default_payable_account_id を設定してください...",
   "context": { "counterparty_id": "..." }
 }
 ```
@@ -89,9 +145,26 @@ GET /api/accounting/counterparties/<id>/balance
 
 主要エラーパターンと対処は `references/troubleshooting.md` を参照。
 
+## 人間専用操作 (ミニオンから提供されない)
+
+以下はデータの根幹に影響するため、ミニオンが自律実行することを禁じている。
+必要な場合は `POST /api/threads` で `@user` メンション + 対象 ID をリンクして人間に依頼する。
+
+| 操作 | 依頼先 (HQ UI) |
+|------|---------------|
+| 決算期の close / reopen / 期首残高設定 | `/accounting/periods` |
+| 法人税計算の finalize / journalize / reopen | `/accounting/tax-calculations/:id` ウィザード末尾 |
+| 仕訳・科目・取引先・立替・税計算の DELETE | 各リスト画面 |
+| 科目の rename / アーカイブ (PATCH) | `/accounting/accounts` |
+| 立替経費の settle / bulk-settle | `/accounting/reimbursements` |
+| レシートと仕訳の attach / detach | 各画面 |
+| 人間作成仕訳 (`source='manual'`/`'import'`) の編集 | HQ UI (PATCH は 409 `human_owned_entry`) |
+
 ## 重要な制約
 
-- **確定済み期間(closed)の日付では記帳できない。** 422/409 で拒否される。日付を変えるか PM に再オープン依頼
+- **確定済み期間(closed)の日付では記帳できない。** 409 `period_closed` で拒否される。日付を変えるか PM に再オープン依頼
+- **PATCH できる仕訳は `source='ai_generated'` のものだけ。** 人間作成仕訳は 409 `human_owned_entry`
 - **立替の貸方科目は負債(liability) or 純資産(equity)のみ許容。** 資産勘定の「立替金」(他人のために会社が立て替える勘定)は逆向きなので NG
 - **counterparty マスタは book スコープ。** 別帳簿のIDは使えない
 - **複式簿記の借方=貸方は trigger で強制される。** 自前で計算してから POST すること
+- **税率はユーザー責任で入力する。** 本ツールは税率テーブルを持たない。最新値を調査して入力すること

package/skills/accounting-bookkeeping/references/api-counterparties.md

@@ -2,6 +2,9 @@
 
 取引先マスタは `book_id` スコープ。役員・従業員・仕入先・顧客などを統一管理する。
 
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> 認証は `Authorization: Bearer $API_TOKEN`。人間用 `/api/accounting/*` は使わない。
+
 ## kind の選び方
 
 | kind | 用途 |
@@ -22,24 +25,22 @@
 - 許容: **equity** 型(運用実態として一部の帳簿で利用されるため)
 - NG: **asset/revenue/expense** 型 → API が `invalid_default_payable_account` で 400 を返す
 
-該当科目が無い場合は先に `POST /api/accounting/accounts` で作成すること。
+該当科目が無い場合は先に `POST /accounts` で作成すること。
 
 ## エンドポイント
 
-### GET /api/accounting/counterparties
+### GET /counterparties
 
 ```
 Query:
-  ?q=<部分一致検索>
   ?kind=director,employee  (カンマ区切り)
   ?include_archived=true   (デフォルトはアクティブのみ)
-  ?limit=200               (max 500)
 
 Response:
   { "counterparties": [{ id, book_id, name, kind, member_id, default_payable_account_id, is_archived, ... }] }
 ```
 
-### POST /api/accounting/counterparties
+### POST /counterparties
 
 ```
 Body:
@@ -50,7 +51,7 @@ Body:
     "default_payable_account_id": "<account uuid>"
   }
 
-Response 201: { "counterparty": {...} }
+Response: { "counterparty": {...} }
 
 エラー:
   400 invalid_kind                       — kind 不正
@@ -58,14 +59,23 @@ Response 201: { "counterparty": {...} }
   409 counterparty_name_conflict         — 同名のアクティブな取引先が存在 (context.existing_id 参照)
 ```
 
-### GET /api/accounting/counterparties/[id]
+### GET /counterparties/:counterpartyId
+
+取引先詳細と残高サマリ。補助元帳の照会はこのエンドポイントを使う。
 
 ```
-Response: { "counterparty": {...} }
+Response:
+  {
+    "counterparty": {...},
+    "balance": { "debit_total": ..., "credit_total": ..., "net": ... }
+  }
 404 counterparty_not_found
 ```
 
-### PATCH /api/accounting/counterparties/[id]
+残高の符号: 資産/費用は `debit - credit`、負債/純資産/収益は `credit - debit`。
+明細レベルの内訳が必要な場合は `GET /entries?...` で当該取引先の line を含む仕訳を取得して集計する。
+
+### PATCH /counterparties/:counterpartyId
 
 ```
 Body (全て任意):
@@ -74,36 +84,10 @@ Body (全て任意):
 Response: { "counterparty": {...} }
 ```
 
-### DELETE /api/accounting/counterparties/[id]
-
-ソフト削除(`is_archived=true`)。物理削除はしない(過去仕訳の参照を保持するため)。
-
-```
-エラー:
-  409 has_unsettled_reimbursements — 未精算の立替が残っているとアーカイブ不可
-```
-
-### GET /api/accounting/counterparties/[id]/balance
+`is_archived: true` でソフトアーカイブできる。未精算の立替が残っている取引先は
+409 `has_unsettled_reimbursements` でアーカイブ不可(精算は人間専用なので人間に依頼)。
 
-補助元帳。取引先別の残高(勘定科目別)と明細リスト。
+### 取引先の削除 — **人間専用**
 
-```
-Query:
-  ?as_of=YYYY-MM-DD  (任意。これより前の仕訳のみ集計)
-  ?limit=500         (明細最大件数)
-
-Response:
-  {
-    "counterparty": {...},
-    "balance_by_account": [
-      { "account_id", "code", "name", "type", "debit", "credit", "balance" }
-    ],
-    "lines": [
-      { "id", "account_id", "debit", "credit", "memo", "entry": {...}, "account": {...} }
-    ],
-    "unsettled_reimbursements_count": 2,
-    "as_of": null
-  }
-```
-
-残高の符号: 資産/費用は `debit - credit`、負債/純資産/収益は `credit - debit`。
+物理削除 (`DELETE`) はミニオンには提供されない(過去仕訳の参照を保持するため)。
+不要な取引先は上記 PATCH の `is_archived: true` でアーカイブする。完全削除が必要な場合は人間に依頼する。

package/skills/accounting-bookkeeping/references/api-expense-reimbursement.md

@@ -2,15 +2,24 @@
 
 立替経費は「立替記帳の仕訳」と「精算の仕訳」の対応関係を保持する別レイヤ。両仕訳の line に同じ `counterparty_id` が付与される。
 
+> パスはすべて **ミニオン用** `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+> ミニオン側のリソース名は **`reimbursements`**(人間用の `expense-reimbursements` ではない)。
+> 認証は `Authorization: Bearer $API_TOKEN`。
+
+## ミニオンが扱える操作
+
+ミニオンに提供されるのは **一覧取得 (GET)** と **記帳 (POST)** の2つだけ。
+精算・編集・削除は実出金や取消を伴うため **人間専用**(後述)。
+
 ## 仕訳パターン
 
-**立替記帳時:**
+**立替記帳時 (POST /reimbursements が自動生成):**
 ```
 (借) 費用科目                 amount    [counterparty_id=<立替者>]
   (貸) counterparty.default_payable_account_id   amount    [counterparty_id=<立替者>]
 ```
 
-**精算時:**
+**精算時 (人間が HQ UI で実行):**
 ```
 (借) counterparty.default_payable_account_id   amount    [counterparty_id=<立替者>]
   (貸) wallet_account (現金 or 普通預金)         amount    [counterparty_id=<立替者>]
@@ -18,9 +27,27 @@
 
 ## エンドポイント
 
-### POST /api/accounting/expense-reimbursements
+### GET /reimbursements
+
+```
+Query:
+  ?status=settled|unsettled|all   (default: 全件相当。未精算だけ見たいときは unsettled)
+  ?counterparty_id=<uuid>
+  ?limit=100&offset=0
+
+Response:
+  {
+    "reimbursements": [{
+      id, paid_by_counterparty_id, occurred_on, amount, description,
+      expense_journal_entry_id, settled_at, settlement_journal_entry_id,
+      counterparty: { id, name, kind }
+    }]
+  }
+```
+
+### POST /reimbursements
 
-立替経費を記帳する。
+立替経費を記帳する。仕訳(借方=expense, 貸方=payable)を自動生成する。
 
 ```
 Body:
@@ -30,13 +57,10 @@ Body:
     "amount": 1000,
     "expense_account_id": "<費用科目 uuid>",
     "description": "新幹線代 東京→大阪",      // 任意
-    "receipt_ids": ["<receipt uuid>"],         // 任意。既存の未添付レシートを紐付ける
-    "category_dimensions": {                   // 任意。一般社団法人プロファイル等で expense 行に
-      "net_asset_restriction": "general"        // ディメンションが必要な場合に指定。expense 行(借方)のみに付与される
-    }
+    "payable_account_id": "<貸方科目 uuid>"   // 任意。省略時は counterparty.default_payable_account_id を使用
   }
 
-Response 201: { "reimbursement": { "id", "expense_journal_entry_id" } }
+Response: { "reimbursement": { "id", "expense_journal_entry_id" } }
 
 主要エラー:
   400 invalid_amount                       — amount が正の数値でない
@@ -44,137 +68,26 @@ Response 201: { "reimbursement": { "id", "expense_journal_entry_id" } }
   400 invalid_expense_account_type         — expense_account_id が expense 型でない
   404 counterparty_not_found               — 立替者が見つからない (next_action: POST で先に作成)
   409 counterparty_archived                — 立替者がアーカイブ済み
-  409 period_closed                        — occurred_on が締め済期間内
-  422 missing_default_payable_account      — 立替者の default_payable_account_id が未設定
-```
-
-### PATCH /api/accounting/expense-reimbursements/[id]
-
-未精算の立替経費を編集する。仕訳ヘッダ・明細・reimbursement ヘッダを整合させた状態で更新する。
-精算済みの立替は編集できない (先に精算を取り消す必要がある)。
-**counterparty (立替者) の変更はサポートしない** — 変更する場合は削除して再作成すること。
-
-```
-Body (すべて optional、最低1つは渡す):
-  {
-    "occurred_on": "YYYY-MM-DD",
-    "amount": 1200,
-    "expense_account_id": "<費用科目 uuid>",
-    "description": "新幹線代 東京→大阪 (金額訂正)",
-    "category_dimensions": { "net_asset_restriction": "general" }
-  }
-
-Response 200: { "reimbursement": { "id", "expense_journal_entry_id" } }
-
-主要エラー:
-  400 invalid_amount / invalid_date / expense_account_not_found / invalid_expense_account_type
-  404 reimbursement_not_found
-  409 already_settled                — 精算済み (next_action: 精算を先に取り消す)
-  409 period_closed                  — 変更前後の日付が締め済期間内
-  422 missing_default_payable_account
-```
-
-### POST /api/accounting/expense-reimbursements/[id]/settle
-
-立替を全額精算する。**部分精算は非対応**。
-
-```
-Body:
-  {
-    "settled_on": "YYYY-MM-DD",
-    "wallet_account_id": "<is_wallet=true の account uuid>"
-  }
-
-Response: { "reimbursement": { "id", "expense_journal_entry_id" } }
-  ※ expense_journal_entry_id は精算仕訳のIDが返る
-
-主要エラー:
-  404 reimbursement_not_found
-  409 already_settled                — 既に精算済み (context.settled_at 参照)
-  409 period_closed                  — settled_on が締め済期間内
-  400 wallet_account_not_found       — 支払口座が見つからない
-  400 not_a_wallet_account           — is_wallet=false の科目を指定した
-  422 missing_default_payable_account — 立替者の貸方科目が後から消去された場合
-```
-
-### POST /api/accounting/expense-reimbursements/bulk-settle
-
-複数の立替を1本の精算仕訳でまとめて精算する。実運用で「役員Aの今月分3件を1回の振込で精算」する典型ケース向け。
-
-```
-Body:
-  {
-    "reimbursement_ids": ["<uuid>", "<uuid>", ...],  // 未精算の立替IDを1件以上
-    "settled_on": "YYYY-MM-DD",
-    "wallet_account_id": "<is_wallet=true の account uuid>"
-  }
-
-仕訳 (合計1本):
-  (借) counterparty.default_payable_account   sum(amounts)   [counterparty_id=<立替者>]
-    (貸) wallet_account                         sum(amounts)   [counterparty_id=<立替者>]
-
-Response: { "settlement_entry_id": "<uuid>", "reimbursement_ids": ["<uuid>", ...] }
-
-制約:
-  - すべての reimbursement が同一 counterparty に属すこと (混在不可)
-  - 全額精算のみ (部分精算は非対応)
-
-主要エラー:
-  400 missing_required_fields        — reimbursement_ids が空 / 必須項目欠落
-  400 multiple_counterparties        — 異なる立替者が混在 (context.counterparty_ids)
-  400 not_a_wallet_account           — 支払口座が is_wallet=false
-  404 reimbursement_not_found        — 一部のIDが見つからない (context.missing_ids)
-  409 already_settled                — 一部が既に精算済み (context.settled_ids)
-  409 period_closed                  — settled_on が締め済期間内
-  422 missing_default_payable_account — 立替者の貸方科目が未設定
-```
-
-データモデル: 精算仕訳と立替の関係は `accounting_reimbursement_settlements` (junction) で多対多管理される。単発 `/settle` 経由でも junction に行が書かれるため、補助元帳の集計クエリは junction を起点に書くと統一感が出る。`accounting_expense_reimbursements.settlement_journal_entry_id` は最後に紐付いた精算仕訳のポインタとして残る (後方互換用)。
-
-### GET /api/accounting/expense-reimbursements
-
+  409 code: 'period_closed'                — occurred_on が締め済期間内
+  422 missing_default_payable_account      — 立替者の default_payable_account_id が未設定 (先に PATCH /counterparties で設定)
 ```
-Query:
-  ?counterparty_id=<uuid>
-  ?settled=true|false  (未指定なら両方)
-  ?from=YYYY-MM-DD&to=YYYY-MM-DD  (occurred_on で絞り込み)
-  ?limit=200
-
-Response:
-  {
-    "reimbursements": [{
-      id, paid_by_counterparty_id, occurred_on, amount, description,
-      expense_journal_entry_id, settled_at, settlement_journal_entry_id,
-      counterparty: { id, name, kind }
-    }]
-  }
-```
-
-### GET /api/accounting/expense-reimbursements/[id]
 
-```
-Response:
-  {
-    "reimbursement": {
-      ...,
-      counterparty: {...},
-      expense_entry: {...},
-      settlement_entry: null|{...}
-    }
-  }
-```
+## 人間専用操作 (ミニオンから提供されない)
 
-### DELETE /api/accounting/expense-reimbursements/[id]
+以下は実出金・取消を伴うため、`POST /api/threads` で `@user` メンションして HQ UI 操作を依頼する。
 
-立替記帳の取消(精算前のみ)。関連する立替仕訳も同時に削除される。
+| 操作 | 説明 / 依頼先 |
+|------|--------------|
+| `settle` (個別精算) | 立替を全額精算。HQ UI `/accounting/reimbursements` の精算ボタン |
+| `bulk-settle` (一括精算) | 同一立替者の複数件を1本の精算仕訳でまとめて精算 |
+| `PATCH` (編集) | 未精算立替の金額・科目訂正 |
+| `DELETE` (取消) | 精算前の立替記帳の取消 |
 
-```
-エラー:
-  409 already_settled — 精算済みは取消不可
-```
+ミニオンができるのは「未精算リストを `GET /reimbursements?status=unsettled` で把握 → 人間に精算を依頼」まで。
 
 ## ベストプラクティス
 
-- 立替者を識別できない場合は推測しない。`GET /counterparties?q=<name>` で検索し、複数候補がある場合は **PMに確認** すること
+- 立替者を識別できない場合は推測しない。`GET /counterparties?kind=director,employee` で検索し、複数候補がある場合は **PMに確認** すること
 - 「立替金」(asset 勘定として存在することがある)は会社が他者のために立て替えた場合の科目。**役員/従業員が立て替えた場合の貸方には使わない** こと
-- 描かれた `next_action` を必ず読む。recover 可能なエラーは指示通りに対処
+- 返ってきた `next_action` を必ず読む。recover 可能なエラーは指示通りに対処
+- **記帳に失敗して中途半端な状態が残った場合、ミニオンは DELETE できない。** `POST /api/threads` で状況を報告し、人間に取消を依頼すること