@geekbeer/minion 4.1.2 → 4.2.0

package/docs/api-reference.md

@@ -809,20 +809,22 @@ Base path: All endpoints are prefixed with `/api/minion` by the agent's API clie
 |--------|----------|-------------|
 | GET | `/api/minion/me/projects` | 参加プロジェクト一覧（role 含む） |
 
+Query parameters:
+- `workspace_id` (optional, UUID): 指定したワークスペースに属するプロジェクトのみ返す。省略すると参加している全プロジェクト（複数ワークスペース横断）を返す。
+
 Response:
 ```json
-[
-  {
-    "id": "uuid",
-    "name": "project-name",
-    "description": "...",
-    "github_owner": "org",
-    "github_repo": "repo",
-    "role": "pm",
-    "created_at": "...",
-    "updated_at": "..."
-  }
-]
+{
+  "projects": [
+    {
+      "id": "uuid",
+      "name": "project-name",
+      "description": "...",
+      "workspace_id": "uuid",
+      "role": "pm"
+    }
+  ]
+}
 ```
 
 `role` is one of `"pm"` (project manager), `"engineer"`, or `"accountant"`.
@@ -2107,56 +2109,74 @@ DAGスキルノードの `skill_version_id` は **オプション** です。
 ローカルエージェントの `/api/project-memories` は上記 HQ API へのプロキシ。
 詳細なリクエスト/レスポンス仕様はローカル API セクションの「Project Memories」を参照。
 
-### Notes (HQ, プロジェクトノート)
+### Notes (HQ, ワークスペース／プロジェクトノート)
+
+ノートはワークスペース直下に保存され、任意で 1 つ以上のプロジェクトにリンクできる(`note_project_links`)。
+**テキストベースの成果物（レポート、調査結果、要約等）はノートに保存すること。** HQダッシュボードでユーザーが即座に閲覧・編集・検索でき、バージョン管理もされる。
+
+ミニオンには**ワークスペース経由API**と**プロジェクト経由API**の2系統がある:
 
-プロジェクトに紐づくノート。**テキストベースの成果物（レポート、調査結果、要約等）はノートに保存すること。**
-ノートはHQダッシュボードでユーザーが即座に閲覧・編集・検索でき、バージョン管理もされる。
+- **ワークスペース経由** — 自分が所属するワークスペース内のすべてのノートにアクセス可能 (プロジェクト未リンクのノート含む)。一般的な検索・整理に使う
+- **プロジェクト経由** — 作業コンテキストが特定プロジェクトに紐づいているときに、そのプロジェクトのノートだけを絞り込む用途。プロジェクトメンバーシップで認可される
+
+**削除エンドポイントは存在しない**(事故防止のため人間操作限定)。アーカイブが必要な場合は `status=archived` で PATCH すること。
+
+#### Workspace-scoped Notes
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/minion/projects/:projectId/notes` | プロジェクトのノート一覧。Query: `?status=active&include_content=true` |
-| POST | `/api/minion/projects/:projectId/notes` | ノートを作成しプロジェクトにリンク |
-| GET | `/api/minion/projects/:projectId/notes/:noteId` | ノート詳細（全文含む） |
-| PATCH | `/api/minion/projects/:projectId/notes/:noteId` | ノートを更新（内容変更時にバージョン自動作成） |
-| GET | `/api/minion/projects/:projectId/notes/search?q=keyword` | ノートを全文検索 |
+| GET | `/api/minion/workspaces/:id/notes` | ワークスペースのノート一覧。Query: `?status=active&search=&project_id=&include_content=true` |
+| POST | `/api/minion/workspaces/:id/notes` | ノート作成。Body: `{title, content?, project_ids?: string[]}`。`project_ids` 指定時は自動でリンク |
+| GET | `/api/minion/workspaces/:id/notes/:noteId` | ノート詳細(全文) |
+| PATCH | `/api/minion/workspaces/:id/notes/:noteId` | 更新(内容変更時にバージョン自動作成)。Body: `{title?, content?, status?, change_summary?}` |
+| GET | `/api/minion/workspaces/:id/notes/search?q=keyword` | ワークスペース全体を全文検索 |
 
-POST `/api/minion/projects/:projectId/notes` body:
+POST `/api/minion/workspaces/:id/notes` body:
 ```json
 {
   "title": "調査レポート: ユーザー行動分析",
-  "content": "## 概要\n..."
+  "content": "## 概要\n...",
+  "project_ids": ["<uuid>"]
 }
 ```
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `title` | string | Yes | ノートのタイトル |
-| `content` | string | No | ノートの本文（Markdown） |
+| `title` | string | Yes | ワークスペース内で一意である必要がある |
+| `content` | string | No | Markdown本文 |
+| `project_ids` | string[] | No | リンクするプロジェクト(ワークスペースに属している必要あり) |
 
-PATCH `/api/minion/projects/:projectId/notes/:noteId` body:
-```json
-{
-  "title": "更新されたタイトル",
-  "content": "更新された本文",
-  "change_summary": "データを追加"
-}
-```
+#### Project-scoped Notes
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `title` | string | No | 新しいタイトル |
-| `content` | string | No | 新しい本文 |
-| `change_summary` | string | No | 変更の要約（バージョン履歴に記録） |
+特定プロジェクトのノートだけを絞り込みたいときに使う。認可は `project_members` を経由。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/projects/:projectId/notes` | プロジェクトのノート一覧。Query: `?status=active&include_content=true` |
+| POST | `/api/minion/projects/:projectId/notes` | ノート作成 + 当該プロジェクトに自動リンク |
+| GET | `/api/minion/projects/:projectId/notes/:noteId` | ノート詳細(全文含む) |
+| PATCH | `/api/minion/projects/:projectId/notes/:noteId` | ノートを更新(内容変更時にバージョン自動作成) |
+| GET | `/api/minion/projects/:projectId/notes/search?q=keyword` | プロジェクト内のノートを全文検索 |
+
+PATCH body は workspace 版と共通: `{title?, content?, change_summary?}` (status は workspace 経由のみ受理)。
 
 #### hq CLI ラッパー
 
 ```bash
+# プロジェクトスコープ
 hq note create <project_id> --title "タイトル" --content "本文"
 hq note create <project_id> --title "タイトル" --file /tmp/report.md
 hq note update <project_id> <note_id> --content "更新内容" --change-summary "修正理由"
 hq note list <project_id>
 hq note get <project_id> <note_id>
 hq note search <project_id> "キーワード"
+
+# ワークスペーススコープ (プロジェクト紐づけなしも対象)
+hq note create --workspace <workspace_id> --title "タイトル" --content "本文"
+hq note update --workspace <workspace_id> <note_id> --content "更新内容"
+hq note list --workspace <workspace_id>
+hq note get --workspace <workspace_id> <note_id>
+hq note search --workspace <workspace_id> "キーワード"
 ```
 
 ### Meeting Rooms 🧪 (HQ, experimental, v3.59.0〜)

package/linux/bin/hq

@@ -19,12 +19,17 @@
 #   hq list workspaces                    - List workspaces this minion belongs to
 #   hq list dag-workflows [project_id]    - List DAG workflows (optionally filter by project)
 #   hq note create <project_id> --title "Title" --content "Body" [--file path]
-#                                         - Create a note linked to the project
+#   hq note create --workspace <workspace_id> --title "Title" --content "Body" [--file path] [--project-ids <id,id>]
+#                                         - Create a note (project- or workspace-scoped)
 #   hq note update <project_id> <note_id> --content "Body" [--title "Title"] [--file path] [--change-summary "summary"]
+#   hq note update --workspace <workspace_id> <note_id> --content "Body" [--title "Title"] [--status active|archived]
 #                                         - Update an existing note
 #   hq note list <project_id>             - List notes in the project
+#   hq note list --workspace <workspace_id>  - List notes in the workspace (incl. project-unlinked)
 #   hq note get <project_id> <note_id>    - Get a single note with full content
+#   hq note get --workspace <workspace_id> <note_id>  - Same, workspace-scoped
 #   hq note search <project_id> <query>   - Search notes in the project
+#   hq note search --workspace <workspace_id> <query> - Search across the whole workspace
 #   hq create dag-workflow <body.json>    - Create a DAG workflow (PM only). Body: {project_id, name, graph?, ...}
 #   hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only). Body: {graph?, content?, ...}
 #   hq publish dag-workflow <id>          - Publish the draft as a new version (PM only, validated)
@@ -163,10 +168,15 @@ print_usage() {
   echo "  hq list workspaces                    - List workspaces this minion belongs to" >&2
   echo "  hq list dag-workflows [project_id]    - List DAG workflows (optionally by project)" >&2
   echo "  hq note create <project_id> --title \"Title\" --content \"Body\" [--file path]" >&2
+  echo "  hq note create --workspace <ws_id> --title \"Title\" --content \"Body\" [--project-ids <id,id>]" >&2
   echo "  hq note update <project_id> <note_id> --content \"Body\" [--title \"Title\"] [--file path]" >&2
-  echo "  hq note list <project_id>             - List notes in the project" >&2
-  echo "  hq note get <project_id> <note_id>    - Get a single note" >&2
-  echo "  hq note search <project_id> <query>   - Search notes in the project" >&2
+  echo "  hq note update --workspace <ws_id> <note_id> --content \"Body\" [--title \"Title\"] [--status active|archived]" >&2
+  echo "  hq note list <project_id>                 - List notes in the project" >&2
+  echo "  hq note list --workspace <ws_id>          - List notes in the workspace" >&2
+  echo "  hq note get <project_id> <note_id>        - Get a single note" >&2
+  echo "  hq note get --workspace <ws_id> <note_id> - Get a single note (workspace-scoped)" >&2
+  echo "  hq note search <project_id> <query>       - Search notes in the project" >&2
+  echo "  hq note search --workspace <ws_id> <query> - Search notes across the workspace" >&2
   echo "  hq create dag-workflow <body.json>    - Create a DAG workflow (PM only)" >&2
   echo "  hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only)" >&2
   echo "  hq publish dag-workflow <id>          - Publish the draft as a new version (PM only)" >&2
@@ -310,22 +320,38 @@ case "${1:-}" in
 
   note)
     action="${2:-}"
+    shift 2 || true
+    # Resolve scope: either "--workspace <ws_id>" (must be first) or positional <project_id>.
+    note_base=""
+    if [ "${1:-}" = "--workspace" ]; then
+      ws_id="${2:-}"
+      if [ -z "$ws_id" ]; then
+        echo "Error: --workspace requires a workspace_id" >&2
+        exit 1
+      fi
+      note_base="$BASE_URL/workspaces/$ws_id/notes"
+      shift 2
+    else
+      project_id="${1:-}"
+      if [ -z "$project_id" ] || [ "${project_id#--}" != "$project_id" ]; then
+        echo "Usage: hq note $action <project_id> ... | hq note $action --workspace <ws_id> ..." >&2
+        exit 1
+      fi
+      note_base="$BASE_URL/projects/$project_id/notes"
+      shift
+    fi
     case "$action" in
       create)
-        project_id="${3:-}"
-        if [ -z "$project_id" ]; then
-          echo "Usage: hq note create <project_id> --title \"Title\" --content \"Body\" [--file path]" >&2
-          exit 1
-        fi
-        shift 3
         note_title=""
         note_content=""
         note_file=""
+        project_ids_csv=""
         while [ $# -gt 0 ]; do
           case "$1" in
             --title) note_title="$2"; shift 2 ;;
             --content) note_content="$2"; shift 2 ;;
             --file) note_file="$2"; shift 2 ;;
+            --project-ids) project_ids_csv="$2"; shift 2 ;;
             *) echo "Unknown option: $1" >&2; exit 1 ;;
           esac
         done
@@ -344,38 +370,47 @@ case "${1:-}" in
           echo "Error: --content or --file is required" >&2
           exit 1
         fi
-        # Build JSON body using jq or python3
         if command -v jq &>/dev/null; then
           body=$(jq -n --arg t "$note_title" --arg c "$note_content" '{title: $t, content: $c}')
+          if [ -n "$project_ids_csv" ]; then
+            body=$(echo "$body" | jq --arg ids "$project_ids_csv" '. + {project_ids: ($ids | split(","))}')
+          fi
         elif command -v python3 &>/dev/null; then
-          body=$(python3 -c "import json,sys; print(json.dumps({'title': sys.argv[1], 'content': sys.argv[2]}))" "$note_title" "$note_content")
+          body=$(python3 -c "
+import json, sys
+d = {'title': sys.argv[1], 'content': sys.argv[2]}
+if sys.argv[3]:
+    d['project_ids'] = [s for s in sys.argv[3].split(',') if s]
+print(json.dumps(d))
+" "$note_title" "$note_content" "$project_ids_csv")
         else
           echo "Error: jq or python3 is required to build JSON" >&2
           exit 1
         fi
         tmpfile=$(mktemp)
         echo "$body" > "$tmpfile"
-        send_json_request POST "$BASE_URL/projects/$project_id/notes" "$tmpfile"
+        send_json_request POST "$note_base" "$tmpfile"
         rm -f "$tmpfile"
         ;;
       update)
-        project_id="${3:-}"
-        note_id="${4:-}"
-        if [ -z "$project_id" ] || [ -z "$note_id" ]; then
-          echo "Usage: hq note update <project_id> <note_id> --content \"Body\" [--title \"Title\"] [--file path] [--change-summary \"summary\"]" >&2
+        note_id="${1:-}"
+        if [ -z "$note_id" ]; then
+          echo "Error: <note_id> is required" >&2
           exit 1
         fi
-        shift 4
+        shift
         note_title=""
         note_content=""
         note_file=""
         change_summary=""
+        note_status=""
         while [ $# -gt 0 ]; do
           case "$1" in
             --title) note_title="$2"; shift 2 ;;
             --content) note_content="$2"; shift 2 ;;
             --file) note_file="$2"; shift 2 ;;
             --change-summary) change_summary="$2"; shift 2 ;;
+            --status) note_status="$2"; shift 2 ;;
             *) echo "Unknown option: $1" >&2; exit 1 ;;
           esac
         done
@@ -386,16 +421,16 @@ case "${1:-}" in
           fi
           note_content=$(cat "$note_file")
         fi
-        if [ -z "$note_content" ] && [ -z "$note_title" ]; then
-          echo "Error: at least --content, --file, or --title is required" >&2
+        if [ -z "$note_content" ] && [ -z "$note_title" ] && [ -z "$note_status" ]; then
+          echo "Error: at least --content, --file, --title, or --status is required" >&2
           exit 1
         fi
-        # Build JSON body
         if command -v jq &>/dev/null; then
           body="{}"
           [ -n "$note_title" ] && body=$(echo "$body" | jq --arg t "$note_title" '. + {title: $t}')
           [ -n "$note_content" ] && body=$(echo "$body" | jq --arg c "$note_content" '. + {content: $c}')
           [ -n "$change_summary" ] && body=$(echo "$body" | jq --arg s "$change_summary" '. + {change_summary: $s}')
+          [ -n "$note_status" ] && body=$(echo "$body" | jq --arg st "$note_status" '. + {status: $st}')
         elif command -v python3 &>/dev/null; then
           body=$(python3 -c "
 import json, sys
@@ -403,20 +438,20 @@ d = {}
 if sys.argv[1]: d['title'] = sys.argv[1]
 if sys.argv[2]: d['content'] = sys.argv[2]
 if sys.argv[3]: d['change_summary'] = sys.argv[3]
+if sys.argv[4]: d['status'] = sys.argv[4]
 print(json.dumps(d))
-" "$note_title" "$note_content" "$change_summary")
+" "$note_title" "$note_content" "$change_summary" "$note_status")
         else
           echo "Error: jq or python3 is required to build JSON" >&2
           exit 1
         fi
         tmpfile=$(mktemp)
         echo "$body" > "$tmpfile"
-        # Use PATCH for update
         response=$(curl -s -w "\n%{http_code}" -X PATCH \
           -H "Authorization: Bearer $API_TOKEN" \
           -H "Content-Type: application/json" \
           --data-binary "@$tmpfile" \
-          "$BASE_URL/projects/$project_id/notes/$note_id")
+          "$note_base/$note_id")
         rm -f "$tmpfile"
         http_code=$(echo "$response" | tail -1)
         body_out=$(echo "$response" | sed '$d')
@@ -429,30 +464,22 @@ print(json.dumps(d))
         fi
         ;;
       list)
-        project_id="${3:-}"
-        if [ -z "$project_id" ]; then
-          echo "Usage: hq note list <project_id>" >&2
-          exit 1
-        fi
-        fetch_resource "$BASE_URL/projects/$project_id/notes?include_content=false"
+        fetch_resource "$note_base?include_content=false"
         ;;
       get)
-        project_id="${3:-}"
-        note_id="${4:-}"
-        if [ -z "$project_id" ] || [ -z "$note_id" ]; then
-          echo "Usage: hq note get <project_id> <note_id>" >&2
+        note_id="${1:-}"
+        if [ -z "$note_id" ]; then
+          echo "Error: <note_id> is required" >&2
           exit 1
         fi
-        fetch_resource "$BASE_URL/projects/$project_id/notes/$note_id"
+        fetch_resource "$note_base/$note_id"
         ;;
       search)
-        project_id="${3:-}"
-        query="${4:-}"
-        if [ -z "$project_id" ] || [ -z "$query" ]; then
-          echo "Usage: hq note search <project_id> <query>" >&2
+        query="${1:-}"
+        if [ -z "$query" ]; then
+          echo "Error: <query> is required" >&2
           exit 1
         fi
-        # URL-encode the query
         if command -v jq &>/dev/null; then
           encoded=$(printf '%s' "$query" | jq -sRr @uri)
         elif command -v python3 &>/dev/null; then
@@ -460,7 +487,7 @@ print(json.dumps(d))
         else
           encoded="$query"
         fi
-        fetch_resource "$BASE_URL/projects/$project_id/notes/search?q=$encoded"
+        fetch_resource "$note_base/search?q=$encoded"
         ;;
       *)
         echo "Unknown note action: $action" >&2

package/linux/routes/chat.js

@@ -391,7 +391,7 @@ async function buildContextPrefix(message, context, sessionId, workspaceId, refe
       '[ファイル出力ルール]',
       '成果物の保存先は以下のルールに従うこと。`/home/minion/` 直下にファイルを保存しないこと。',
       '',
-      '- **テキスト成果物**（レポート、調査結果、要約等）→ ノートに保存: `hq note create <project_id> --title "タイトル" --content "本文"`',
+      '- **テキスト成果物**（レポート、調査結果、要約等）→ ノートに保存: `hq note create <project_id> --title "タイトル" --content "本文"` (プロジェクト紐づけなしは `hq note create --workspace <ws_id> ...`)',
       '- **バイナリファイル**（PDF、画像、ZIP等）→ `~/files/` に配置（ユーザーがHQからダウンロード可能）',
       '- **一時ファイル** → `/tmp/` に配置（作業後に削除）',
       '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/rules/core.md

@@ -445,28 +445,32 @@ display_name が同じユーザーが同一ワークスペースに複数いる
 
 ### ノートへの保存 (`hq note` コマンド)
 
-テキストベースの成果物は原則ノートに保存する。ノートはプロジェクトに紐づき、HQダッシュボードで閲覧できる。
+テキストベースの成果物は原則ノートに保存する。ノートはワークスペース直下に保存され、任意で 1 つ以上のプロジェクトにリンクできる。HQダッシュボードで閲覧・編集・検索でき、バージョン管理もされる。
+
+スコープの使い分け:
+
+- **プロジェクトスコープ** — 作業がプロジェクトに紐づくとき (`hq note ... <project_id>`)。プロジェクトのノートタブから即発見できる
+- **ワークスペーススコープ** — プロジェクトに紐づかない一般的なメモや、ワークスペース横断で検索したいとき (`hq note ... --workspace <workspace_id>`)。プロジェクト未指定でも作成・検索できる
 
 ```bash
-# ノートを作成（プロジェクトに紐づけ）
+# プロジェクトスコープ（作業コンテキストが特定プロジェクト）
 hq note create <project_id> --title "レポートタイトル" --content "本文..."
-
-# 長い内容はファイルから読み込む
 hq note create <project_id> --title "調査結果" --file /tmp/report.md
-
-# 既存ノートを更新
 hq note update <project_id> <note_id> --content "更新された内容"
-
-# ノート一覧を確認
 hq note list <project_id>
-
-# ノート内容を取得
 hq note get <project_id> <note_id>
-
-# ノートを検索
 hq note search <project_id> "キーワード"
+
+# ワークスペーススコープ（プロジェクト未紐づけのノート含む）
+hq note create --workspace <workspace_id> --title "メモ" --content "..."
+hq note update --workspace <workspace_id> <note_id> --content "更新内容"
+hq note list --workspace <workspace_id>
+hq note get --workspace <workspace_id> <note_id>
+hq note search --workspace <workspace_id> "キーワード"
 ```
 
+**削除はミニオンから実行できない**(事故防止のため人間操作限定)。不要なノートは `hq note update ... --status archived` (または PATCH の `status: "archived"`) でアーカイブすること。
+
 ### ノート内のユーザーメンション
 
 人間ユーザーがノート編集UIで `Ctrl+I` を押すと、自分の発言を示すアバター付きチップが行頭に挿入される。マークダウン上は次の形式で永続化される:

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

@@ -97,6 +97,40 @@ Response: { "reimbursement": { "id", "expense_journal_entry_id" } }
   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
 
 ```

package/skills/accounting-bookkeeping/references/api-journal-entries.md

@@ -41,23 +41,27 @@
 }
 ```
 
-**手動仕訳 (manual) - 複合仕訳が必要なときのみ:**
+**手動仕訳 (manual) - 複合仕訳 (N行)。HQ UIでは新規取引フォームの「複合仕訳」タブから入力される:**
 ```
 {
   "entry_type": "manual",
   "entry_date": "2026-05-25",
-  "description": "...",
+  "description": "給与支払 (5月分)",
   "lines": [
-    { "account_id": "...", "debit": 1000, "credit": 0, "memo": "...", "counterparty_id": "..." },
-    { "account_id": "...", "debit": 0, "credit": 1000, "counterparty_id": "..." }
+    { "account_id": "<給料手当>",  "debit": 300000, "credit": 0,     "memo": "基本給",   "counterparty_id": "..." },
+    { "account_id": "<法定福利費>", "debit": 45000,  "credit": 0,     "memo": "社会保険料" },
+    { "account_id": "<預り金>",    "debit": 0,      "credit": 25000, "memo": "源泉所得税" },
+    { "account_id": "<普通預金>",  "debit": 0,      "credit": 320000, "memo": "振込" }
   ]
 }
 ```
 
 **注意点:**
-- `lines` は **必ず2行以上** で **借方合計=貸方合計** であること(DB triggerで強制される)
+- `lines` は **必ず2行以上** で **借方合計=貸方合計** であること (DB triggerで強制される)
+- 各行は **`debit` または `credit` のいずれか一方のみが正の数** であること (両ゼロ・両正は400)
 - `counterparty_id` は任意。付与すると補助元帳でその取引先の明細として集計される
-- 一般社団法人プロファイルでは収益/費用行に `dimensions.net_asset_restriction` が必須
+- 一般社団法人プロファイルで収益/費用行の `dimensions.net_asset_restriction` を省略するとデフォルト値で埋められる (`general`)。明示指定したい場合は `dimensions` フィールドを付ける
+- 「1枚のレシートに会議費と接待交際費が混在」「給与計算」「未払金の振替計上」など、income/expense/transfer の2行構造に収まらないケースで使う
 
 ```
 Response: { "entry": {...} }
@@ -65,6 +69,9 @@ Response: { "entry": {...} }
   400 entry_date and entry_type are required
   400 at least 2 lines required
   400 debit/credit must balance
+  400 manual entry requires at least 2 lines      — lines 配列が短い
+  400 line[N]: exactly one of debit/credit must be positive   — 行レベル不整合
+  400 指定された勘定科目がこの帳簿に存在しません          — account_id が別 book / 削除済
   409 period_closed
 ```
 
@@ -98,3 +105,4 @@ Response: { "entries": [{ ..., lines: [...] }] }
 - **通常の経費は manual で複合仕訳を組まず、`expense` ですませる。** シンプルな分、間違いが少ない
 - **立替経費は仕訳APIで組み立てず、必ず /expense-reimbursements を使う。** 自前で組むと「立替者」軸の集計ができない
 - **dimensions の `net_asset_restriction`** は一般社団法人プロファイル時のみ意味あり。株式会社(corporation-jp)では空でOK
+- **manual を使う判断基準**: 1取引イベントで3科目以上を同時に動かす必要があるとき (給与/源泉/振込のセット、1レシートを複数費用科目に按分 等)。2科目で済むなら income/expense/transfer のいずれかに当てはまる

package/win/routes/chat.js

@@ -452,7 +452,7 @@ async function buildContextPrefix(message, context, sessionId, workspaceId, refe
       '[ファイル出力ルール]',
       '成果物の保存先は以下のルールに従うこと。`/home/minion/` 直下にファイルを保存しないこと。',
       '',
-      '- **テキスト成果物**（レポート、調査結果、要約等）→ ノートに保存: `hq note create <project_id> --title "タイトル" --content "本文"`',
+      '- **テキスト成果物**（レポート、調査結果、要約等）→ ノートに保存: `hq note create <project_id> --title "タイトル" --content "本文"` (プロジェクト紐づけなしは `hq note create --workspace <ws_id> ...`)',
       '- **バイナリファイル**（PDF、画像、ZIP等）→ `~/files/` に配置（ユーザーがHQからダウンロード可能）',
       '- **一時ファイル** → `/tmp/` に配置（作業後に削除）',
       '',