@geekbeer/minion 3.60.5 → 4.1.1

package/LICENSE.md

@@ -0,0 +1,53 @@
+Copyright (c) 2026 GeekBeer Co., Ltd.
+
+Source code in this repository is covered by the Elastic License 2.0.
+The full license text is available at:
+https://www.elastic.co/licensing/elastic-license
+
+----
+
+Elastic License
+
+Acceptance
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+No Liability
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+Definitions
+The licensor is the entity offering these terms, and the software is the software the licensor makes available under these terms, including any portion of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.
+

package/README.md

@@ -1,64 +1,59 @@
-# @geekbeer/minion
+> [!IMPORTANT]
+> This package is the agent runtime for [Minion](https://minion-agent.com), GeekBeer's AI agent platform. It is intended to run on a Minion-managed host (provisioned via the HQ dashboard) and is not designed for standalone use.
 
-AI Agent runtime for Minion - manages heartbeat, status, and skill deployment on VPS.
+# @geekbeer/minion
 
-## Install
+AI agent runtime that runs on a Minion host (Lightsail VPS, Docker container, or self-hosted machine). It exposes a local HTTP API on port `8080`, syncs heartbeats and skills with the HQ server, and runs Claude Code–based workflows and routines via tmux (Linux/macOS) or node-pty (Windows).
 
-```bash
-npm install -g @geekbeer/minion
-```
+Supported platforms: Linux (systemd / supervisord), Windows (NSSM service + WSL), macOS (launchd).
 
-## Usage
+## Documentation
 
-### Setup (VPS)
+Full documentation lives at **https://docs.minion-agent.com**. Start here:
 
-```bash
-minion-cli setup \
-  --hq-url https://minion-agent.com \
-  --minion-id <MINION_ID> \
-  --api-token <API_TOKEN> \
-  --setup-tunnel \
-  --non-interactive
-```
+- [Quickstart](https://docs.minion-agent.com/getting-started/quickstart/) — provision a minion from the HQ dashboard
+- [Concepts](https://docs.minion-agent.com/getting-started/concepts/) — workspaces, projects, skills, workflows, routines
+- [Self-hosting / Provisioning](https://docs.minion-agent.com/getting-started/provisioning/) — bring your own host
+- [Skill authoring](https://docs.minion-agent.com/skills-workflows/skill-authoring/) and [workflow design](https://docs.minion-agent.com/skills-workflows/workflow-design/)
+- [DAG workflow nodes](https://docs.minion-agent.com/skills-workflows/dag-nodes/)
 
-### Service Management
+Japanese documentation is available at https://docs.minion-agent.com/ja/.
 
-```bash
-minion-cli start      # Start the minion agent
-minion-cli stop       # Stop the minion agent
-minion-cli restart    # Restart the minion agent
-minion-cli status     # Show service status
-minion-cli health     # Run health check
-```
+## Install
 
-### Logging
+Most users do **not** install this package manually — the HQ dashboard provisions hosts automatically. For self-hosted setups:
 
 ```bash
-minion-cli log -m "Task completed" -l info -s skill-name
+npm install -g @geekbeer/minion
 ```
 
-### Issue Reporting
+Then follow the [self-hosting guide](https://docs.minion-agent.com/getting-started/provisioning/) to register the host with your HQ workspace.
 
-```javascript
-const { reportIssue } = require('@geekbeer/minion/api')
+## CLI
 
-await reportIssue({
-  title: 'HQ APIで502エラーが発生する',
-  body: '## 状況\n...\n\n## 再現手順\n...',
-  labels: ['bug', 'critical']
-})
-// → { success: true, issue_url: '...', issue_number: 42 }
+```bash
+minion-cli setup --user <USERNAME>     # Install dependencies and register services (Linux/macOS, run as root)
+minion-cli configure --hq-url ... --minion-id ... --api-token ...
+minion-cli start | stop | restart | status
+minion-cli health | diagnose | daemons
+minion-cli set-status <status> [task]
+hq <subcommand>                        # HQ API helper (notes, threads, tasks, memories, etc.)
 ```
 
+On Windows the equivalents are exposed as `minion-cli-win` and `hq-win`; on macOS as `minion-cli-mac` and `hq-mac`. See the [provisioning guide](https://docs.minion-agent.com/getting-started/provisioning/) for end-to-end setup.
+
 ## Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HQ_URL` | Minion HQ server URL | - |
-| `API_TOKEN` | Authentication token | - |
-| `MINION_ID` | Minion UUID | - |
-| `AGENT_PORT` | Agent API listen port | `8080` |
+| Variable | Description |
+|----------|-------------|
+| `HQ_URL` | HQ server URL (leave empty for standalone mode) |
+| `API_TOKEN` | Bearer token for HQ and local API authentication |
+| `MINION_ID` | UUID assigned by HQ on provisioning |
+| `AGENT_PORT` | Local agent API port (default `8080`) |
+| `MINION_USER` | System user that owns the agent process |
 
 ## License
 
-MIT
+This software is licensed under the [Elastic License 2.0](./LICENSE.md) (SPDX: `Elastic-2.0`).
+
+Copyright (c) 2026 GeekBeer Co., Ltd.

package/core/lib/dag-step-poller.js

@@ -161,12 +161,19 @@ async function executeSkillNode(node) {
   )
 
   try {
-    // 1. Claim the node
+    // 1. Claim the node. Response includes `template_vars` containing the
+    //    workspace/project-scope variables resolved on HQ — we merge these
+    //    with minion-local variables for the skill fetch below so HQ-side
+    //    variable updates (e.g. project_variables) take effect on the next
+    //    node execution. Minion-local values win over HQ-scope values,
+    //    matching the cross-scope rule (workspace < project < minion).
+    let hqVars = {}
     try {
-      await dagRequest('/claim-node', {
+      const claimResp = await dagRequest('/claim-node', {
         method: 'POST',
         body: JSON.stringify({ node_execution_id }),
       })
+      hqVars = (claimResp && claimResp.template_vars) || {}
     } catch (claimErr) {
       if (claimErr.statusCode === 409) {
         console.log(`[DagPoller] Node ${node_id} already claimed, skipping`)
@@ -187,7 +194,7 @@ async function executeSkillNode(node) {
     if (skillName) {
       try {
         const minionVars = variableStore.getAll('variables')
-        const mergedVars = { ...minionVars }
+        const mergedVars = { ...hqVars, ...minionVars }
         const varsParam = Object.keys(mergedVars).length > 0
           ? `?vars=${Buffer.from(JSON.stringify(mergedVars)).toString('base64')}`
           : ''

package/core/llm-plugins/types.js

@@ -5,7 +5,7 @@
  * either the Primary (user-facing) session or as a Child (specialist) session
  * dispatched from the Primary via the dispatch MCP server.
  *
- * See: packages/docs-internal/src/content/docs/design/llm-plugin-system.md
+ * See: packages/docs-internal/src/content/docs/design/llm/llm-plugin-system.md
  */
 
 /**

package/core/stores/variable-store.js

@@ -19,7 +19,7 @@
  * Secrets never leave the minion and are never persisted in HQ DB. Variables
  * are non-sensitive and may also be defined at HQ scopes (workspace /
  * project / workflow); see packages/docs-internal/src/content/docs/design/
- * variables-and-secrets.md for the full resolution model.
+ * workflow-execution/variables-and-secrets.md for the full resolution model.
  */
 
 const fs = require('fs')

package/docs/api-reference.md

@@ -1236,6 +1236,9 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 | POST | `/api/minion/dag-workflows/:id/contracts` | 個別contractを追加/更新 |
 | DELETE | `/api/minion/dag-workflows/:id/contracts` | 個別contractを削除 |
 | POST | `/api/minion/dag-workflows/:id/validate` | ドラフトをフル検証（公開せず） |
+| GET | `/api/minion/dag-workflows/:id/variables` | DAGワークフロー変数の一覧取得 |
+| PUT | `/api/minion/dag-workflows/:id/variables` | DAGワークフロー変数を一括 upsert（既存を全削除→再投入） |
+| POST | `/api/minion/dag-workflows/:id/trigger` | 公開済みワークフローを手動実行（pull-model） |
 
 #### POST `/api/minion/dag-workflows/:id/nodes` — ノード追加
 
@@ -1482,6 +1485,80 @@ body なし。現在のドラフトを `validateDagGraph` でフル検証し結
 }
 ```
 
+#### GET / PUT `/api/minion/dag-workflows/:id/variables` — DAGワークフロー変数
+
+DAGワークフロー単位のキー/値ペア。スキル本文の `{{VAR_NAME}}` プレースホルダーに展開される。展開タイミングは `claim-node` のレスポンス `template_vars` に乗って降ってくる経路で、変更は **次のノード claim から即時反映** される。
+
+**スコープ優先順位** (narrower wins): `workspace_variables` < `project_variables` < `dag_workflow_variables` < minion-local。
+
+**バリデーション**:
+- `key`: `^[A-Za-z_][A-Za-z0-9_]{0,99}$`（先頭英字またはアンダースコア、最大100文字）
+- `value`: 文字列、最大2000文字
+- 同一 `key` の重複は不可
+
+`GET /api/minion/dag-workflows/:id/variables` レスポンス:
+```json
+{
+  "variables": [
+    { "id": "<uuid>", "key": "TARGET_CATEGORY", "value": "electronics", "created_at": "...", "updated_at": "..." }
+  ]
+}
+```
+
+`PUT /api/minion/dag-workflows/:id/variables` body:
+```json
+{
+  "variables": [
+    { "key": "TARGET_CATEGORY", "value": "electronics" },
+    { "key": "API_BASE_URL", "value": "https://api.example.com" }
+  ]
+}
+```
+
+- バッチ upsert 形式: **既存を全削除 → 渡された配列を全 insert** する（部分更新不可）。
+- 単一変数だけを変更したい場合も、先に GET で現在の集合を取得 → 編集 → PUT で全件送信する。
+- `variables: []` を送ると全削除になる。
+
+レスポンス:
+```json
+{ "success": true, "count": 2 }
+```
+
+エラー時 (400): `{ "error": "Invalid key: 1FOO" }` / `{ "error": "Duplicate key: FOO" }` 等。
+
+#### POST `/api/minion/dag-workflows/:id/trigger` — ワークフロー手動実行
+
+公開済み (`is_active=true` かつ `current_version_id` 設定済み) の DAG ワークフローを手動でトリガーする。HQダッシュボード経由の `POST /api/dag/projects/:projectId/workflows/:dagWfId/trigger` と同じ pull-model で動き、`trigger_source` は `'manual'` として記録される（cron / webhook と区別される）。
+
+Body (任意):
+```json
+{
+  "payload": { "...": "..." }
+}
+```
+
+- `payload` は start ノードの `output_data` に注入され、cascade 経由で下流に伝播する。
+- start ノードに `input_contract` が定義されている場合、`payload` が contract に準拠していないと 400 (`violations` フィールドに違反詳細) が返る。
+- payload を省略すると start ノードは空の出力で完了する。
+
+レスポンス (201):
+```json
+{
+  "execution_id": "<uuid>",
+  "dag_workflow_name": "Order Pipeline",
+  "root_nodes": 3,
+  "total_nodes": 12,
+  "mode": "pull"
+}
+```
+
+エラー応答:
+- 400: ワークフロー非アクティブ / 未公開 / graph 空 / payload 形式不正 / contract 違反
+- 403: ミニオンがプロジェクトの PM でない
+- 404: ワークフロー / プロジェクト未発見
+
+トリガー後はミニオンの `dag-step-poller` が pending ノードを順次拾って実行する。手動実行も含め、すべての DAG 実行は `dag_executions` テーブル + ダッシュボードの実行履歴で追跡できる。
+
 #### 全操作共通のレスポンス形式
 
 ノード/エッジ操作のレスポンスにはワークフロー全体 + `validation` フィールドが含まれる:
@@ -1682,9 +1759,15 @@ Body:
 
 Response (成功 / 201):
 ```json
-{ "success": true, "node_execution_id": "uuid" }
+{
+  "success": true,
+  "node_execution_id": "uuid",
+  "template_vars": { "PROJECT_VAR_NAME": "value", "WORKSPACE_VAR": "value" }
+}
 ```
 
+`template_vars` には claim したノードのコンテキストで解決された **workspace_variables / project_variables / dag_workflow_variables** が narrower-scope-wins (workspace < project < dag_workflow) でマージされて入る。スキルノードの場合は後続の `POST /api/skills/fetch/:name?vars=...` でこの値を base64 JSON として渡し、HQ 側で SKILL.md の `{{VAR}}` を置換する。ミニオンローカル変数はミニオン側で更にレイヤされ、`template_vars` の値を上書きする（cross-scope rule: workspace < project < dag_workflow < minion）。
+
 Response (競合 / 409): 他ミニオンが既に claim 済み、または状態が pending でない場合。
 ```json
 { "error": "Node already claimed or not pending" }
@@ -1949,6 +2032,55 @@ Response:
 
 スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。
 
+**`GET /api/minion/skills/:name` レスポンス**:
+```json
+{
+  "id": "<skill-uuid>",
+  "current_version_id": "<skill-version-uuid>",
+  "name": "variable-injection-test",
+  "display_name": "Variable Injection Test",
+  "type": "workflow",
+  "description": "...",
+  "content": "...",
+  "files": [{ "path": "files/extra.md", "content": "..." }]
+}
+```
+
+**`POST /api/minion/skills` レスポンス**:
+```json
+{
+  "success": true,
+  "skill": {
+    "id": "<skill-uuid>",
+    "name": "variable-injection-test",
+    "workspace_id": "<workspace-uuid>",
+    "current_version_id": "<skill-version-uuid>",
+    "version": 3
+  }
+}
+```
+
+スキルを push してそのまま DAG ノードに組み込む典型フロー:
+
+```bash
+# 1. push してスキルIDを得る
+SKILL_ID=$(curl -s -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  $HQ_URL/api/minion/skills -d '{"name":"my-skill","content":"..."}' | jq -r '.skill.id')
+
+# 2. DAG ノードを追加 (skill_version_id は省略 = 常に最新を追従)
+curl -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  $HQ_URL/api/minion/dag-workflows/$DAG_ID/nodes \
+  -d "{\"type\":\"skill\",\"skill_id\":\"$SKILL_ID\",\"assigned_role\":\"engineer\",\"after\":\"start\",\"before\":\"end\"}"
+```
+
+**スキルバージョンの pin / latest 追従** (DAGスキルノード):
+
+DAGスキルノードの `skill_version_id` は **オプション** です。
+- `skill_version_id` を **省略 / null** にすると、実行時に常に skill の `current_version_id` (最新版) を fetch する（**latest auto-track**）。スキルを push して新バージョンを公開すると、次のノード実行から自動で反映される。
+- `skill_version_id` を **明示的に指定** すると、その特定バージョンに pin される（将来の pinned 実行向け。現状ランタイムは latest 解決を使うが、カラムは保持される）。
+
+旧来の挙動（publish 時に skill_version_id 必須）は廃止済み。`skill_id` のみ指定すれば DAG publish できる。
+
 ### Threads (HQ)
 
 | Method | Endpoint | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.60.5",
+  "version": "4.1.1",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {
@@ -57,5 +57,5 @@
     "claude",
     "automation"
   ],
-  "license": "MIT"
+  "license": "Elastic-2.0"
 }

package/roles/accountant.md

@@ -0,0 +1,42 @@
+# Accountant Role Guidelines
+
+このセッションではあなたは **Accountant** ロールとして行動します。
+
+## 責務
+
+- **記帳**: 取引(仕訳)をHQの会計帳簿に正確に記録する
+- **立替経費の処理**: 役員・従業員が立て替えた経費を記帳・精算する
+- **取引先マスタの整備**: 仕入先・顧客・役員・従業員などの取引先を整備する
+- **補助元帳の照会**: 取引先別の残高・明細を確認し、PMやユーザーへ報告する
+
+## 利用するスキル
+
+会計操作の具体手順とAPI仕様は専用スキルにまとまっています。コアルールにはあえて含めていません(トークン圧迫を避けるため)。
+
+- `/accounting-bookkeeping` — 取引記帳・立替経費・精算・補助元帳の標準フロー
+  - 詳細仕様は `~/.claude/skills/accounting-bookkeeping/references/` 配下を必要時に参照
+
+スキルが未配布の場合は `minion-cli skill fetch accounting-bookkeeping` で取得してください。
+
+## 重要な原則
+
+- **仕訳の確定済み(closed)期は修正しない。** 締め後の仕訳訂正はPMの承認が必要です。
+- **立替経費は取引先(counterparty)を必ず紐付ける。** 「誰の立替か」を後から照会できるようにするため。
+- **default_payable_account_id 未設定の取引先には立替記帳できない。** API が 422 を返します。先に取引先ページで貸方科目を設定してください。
+- **判断に迷ったら勝手に進めない。** 不明な取引・推測の余地がある仕訳は、threadで PM にエスカレーションすること。
+
+## ブロッカー対処
+
+会計記帳中に自力で解決できない問題に遭遇した場合:
+
+1. **まずプロジェクトメモリーを検索** — 過去に同じ取引パターンの記帳例があるか確認
+2. **API のエラーレスポンスを読む** — 会計APIは `next_action` フィールドで次に取るべき操作を返す。これに従う
+3. **自己解決不可なら即ヘルプスレッドを起票** — `attempted_resolution` に試したことを記載
+4. **人間にしか判断できない問題は即エスカレーション** — 法的判断、過去取引の意図確認など
+
+**仕訳を失敗終了させる前に、必ずヘルプスレッドでエスカレーションすること。**
+詳細は `~/.minion/rules/core.md` の「Blocker Handling」セクションを参照。
+
+## 実行コンテキスト
+
+ミニオン変数・シークレット(HQ UIまたはAPI経由で設定)はサーバー起動時に `process.env` にロードされ、会計操作中も利用可能。

package/rules/core.md

@@ -32,6 +32,7 @@ Minion
     - **transform ノードの I/O 型は edge の contract から自動導出**。incoming edge と outgoing edge にそれぞれ contract を必ず貼ること。`transform_instruction` は contract だけで意図が伝わらない場合の補足ヒント（任意）
     - **script ノード (v3.54.0〜)** は LLM を使わない決定的処理用。`script_runtime` (`'python'` or `'node'`) と `script_source` を指定。input_data を stdin で JSON 受け取り → output_data を stdout に JSON 出力する規約。outgoing edge に contract を貼れば transform と同じ runtime validation が走る。LLMトークンを節約したい・出力ブレを許容できない定型処理に使う。詳細は `~/.minion/docs/task-guides.md` の「Script ノード」を参照
     - **fan_out の incoming edge に contract を貼る場合**、`fan_out_source` が指すフィールドが contract 内に `type='array'` として宣言されている必要がある（静的検証で弾かれる）
+    - **スキルノードの skill_version_id は省略可** (v3.60.8〜)。省略するとランタイムが常に skill の最新バージョンを fetch する（latest auto-track）。特定バージョンに pin したい場合のみ明示指定する。`POST /api/minion/skills` のレスポンスで `skill.id` (skill_id) と `skill.current_version_id` の両方が返るので、auto-track 運用なら前者だけ使えばよい
 - **Routine**: ミニオンスコープ。ミニオンローカルの定期タスク。
 - **Project Tasks / Milestones / Sprints**: プロジェクトスコープ。**人間+ミニオンが共有するタスクボード**(5段階Kanban: `backlog`→`todo`→`doing`→`review`→`done`)、ロードマップ(マイルストーン)、アジャイル運用単位(スプリント)。ミニオンは `/api/minion/projects/:projectId/{tasks,milestones,sprints,health}` で操作可能。
   - PMロールは朝のチェックで `/health` を叩いて遅延・停滞タスクを把握、ユーザー要望をエピック+子タスクに分解、スプリントに割り当てて active 化
@@ -225,6 +226,8 @@ Routine 実行中は以下もtmuxセッション環境で利用可能:
 
 **変数**（ワークスペース変数・プロジェクト変数・ワークフロー変数・ミニオン変数）はスキル本文の `{{VAR_NAME}}` テンプレートとして実行時に展開される。スキル作成時にパラメータ化したい値は `{{変数名}}` で記述すること。展開優先順位: ワークスペース < プロジェクト < ワークフロー < ミニオン（後者が優先）。ミニオンが最終オーバーライドとなる設計で、ミニオン運用者がHQ側のデフォルトを差し替えられる経路を保証する。ミニオン変数はさらにミニオン全体スコープとワークスペース別スコープに分かれ、当該ワークスペースのコンテキストで動く実行時はWS別がミニオン全体を上書きする。`/api/variables/*` は `?workspace_id=<uuid>` でスコープ指定（省略時はミニオン全体）。
 
+DAGワークフローでは、HQ側スコープ（workspace/project/dag_workflow）の変数は **`POST /api/dag/minion/claim-node` のレスポンス `template_vars`** に乗って降ってきて、ミニオン側で minion-local 変数とマージしたうえで `POST /api/skills/fetch/:name?vars=...` の base64 JSON に詰めて HQ に渡し、HQ 側で SKILL.md の `{{VAR}}` を置換して返す。つまり HQ-scope 変数の更新は **次のノード claim から反映される**（既存のミニオン上 SKILL.md は次回 fetch で上書きされる）。DAGワークフロー単位の変数は `dag_workflow_variables` テーブルに格納され、DAGエディタの "Variables" ボタンから編集可能。
+
 **シークレット**はワークスペース別にスコープされ、ミニオンローカルのSQLite (`secrets(workspace_id, key, value)`) に保存される。ワークスペース未指定（`workspace_id=''`）はミニオン全体のスコープで、サーバー起動時に `process.env` にロードされ全子プロセスで `$SECRET_NAME` として利用可能。ワークスペース別シークレット（`workspace_id=<uuid>`）は `process.env` にはロードされず、当該ワークスペースのコンテキストで動くランナー（ワークフロー/WSバインドされたルーティン/チャットセッション）にのみ実行時注入される。同名キーが両スコープに存在する場合はワークスペース別が優先。スキル側は常に `$KEY` で参照すればよく、どちらのスコープから来た値かを意識する必要はない。シークレット値はHQ DBに保存されることはなく、HQはpass-throughとして中継するのみ。
 
 デイリーログやメモリーから変数・シークレットの値を推測して使用してはならない。変数は `{{VAR_NAME}}` テンプレートとして定義し、シークレットは環境変数として参照すること。

package/skills/accounting-bookkeeping/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: accounting-bookkeeping
+description: 会計帳簿の記帳・立替経費の処理・補助元帳の照会を行うワークフロー。使用タイミング：(1) 取引を仕訳として記録する時、(2) 役員・従業員の立替経費を記帳・精算する時、(3) 取引先別の残高を確認する時。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` で帳簿を取得し、勘定科目テンプレートはデフォルトで投入済み
+
+## 語彙
+
+| 用語 | 説明 |
+|------|------|
+| **book(帳簿)** | ワークスペースに1冊。仕訳・科目・取引先のスコープ単位 |
+| **account(勘定科目)** | 資産/負債/純資産/収益/費用の5型に分類。`is_wallet=true` のものが支払元(現金/預金)になる |
+| **counterparty(取引先)** | 仕入先・顧客・役員・従業員などのマスタ。`kind` で種別を区別 |
+| **journal entry(仕訳)** | 取引1件のヘッダ。複式簿記なので必ず複数の line を持つ |
+| **journal line(仕訳明細)** | 借方/貸方の各行。`counterparty_id` を付与すると補助元帳が引ける |
+| **expense reimbursement(立替経費)** | 役員/従業員が立て替えた経費。記帳仕訳と精算仕訳の対応を保持する別レイヤ |
+
+## 典型フロー
+
+### A) 通常取引の記帳
+
+```
+1. GET /api/accounting/accounts で勘定科目一覧取得
+2. 入金/出金口座(is_wallet=true)と相手勘定(費用 or 収益)を特定
+3. POST /api/accounting/entries でシンプル仕訳を作成
+   body: { entry_type: 'expense'|'income', entry_date, amount, wallet_account_id, category_account_id, description }
+```
+
+詳細: `references/api-journal-entries.md`
+
+### B) 立替経費の記帳
+
+```
+1. 立替者(役員/従業員)の counterparty を確認
+   - GET /api/accounting/counterparties?q=<name>&kind=director,employee
+   - 見つからなければ POST /api/accounting/counterparties で作成
+   - default_payable_account_id が未設定なら PATCH で先に設定する
+2. POST /api/accounting/expense-reimbursements で記帳
+   body: { paid_by_counterparty_id, occurred_on, amount, expense_account_id, description }
+   → 内部で「(借)費用 / (貸)立替者の負債科目」の仕訳が自動生成される
+3. レシートがあれば事前に POST /api/accounting/receipts でアップロードし、receipt_ids を渡す
+```
+
+詳細: `references/api-expense-reimbursement.md`
+
+### C) 立替経費の精算
+
+```
+1. GET /api/accounting/expense-reimbursements?settled=false で未精算リスト取得
+2. POST /api/accounting/expense-reimbursements/<id>/settle で精算
+   body: { settled_on, wallet_account_id }
+   → 内部で「(借)立替者の負債科目 / (貸)現金or預金」の仕訳が自動生成される
+```
+
+部分精算は非対応。全額精算のみ。
+
+### D) 補助元帳の照会
+
+```
+GET /api/accounting/counterparties/<id>/balance
+→ 取引先別の残高(勘定科目ごと)・明細リスト・未精算立替件数を返す
+```
+
+詳細: `references/api-counterparties.md`
+
+## エラーレスポンスの読み方
+
+会計APIは AI 向けに以下の構造でエラーを返す:
+
+```json
+{
+  "error": "missing_default_payable_account",
+  "message": "取引先「山田太郎」に立替用の貸方科目が未設定です",
+  "next_action": "PATCH /api/accounting/counterparties/<id> で default_payable_account_id を設定してください...",
+  "context": { "counterparty_id": "..." }
+}
+```
+
+**必ず `next_action` を読み、その指示に従うこと。** 推測で適当な処理を試みない。
+
+主要エラーパターンと対処は `references/troubleshooting.md` を参照。
+
+## 重要な制約
+
+- **確定済み期間(closed)の日付では記帳できない。** 422/409 で拒否される。日付を変えるか PM に再オープン依頼
+- **立替の貸方科目は負債(liability) or 純資産(equity)のみ許容。** 資産勘定の「立替金」(他人のために会社が立て替える勘定)は逆向きなので NG
+- **counterparty マスタは book スコープ。** 別帳簿のIDは使えない
+- **複式簿記の借方=貸方は trigger で強制される。** 自前で計算してから POST すること

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

@@ -0,0 +1,109 @@
+# API: 取引先(Counterparties)
+
+取引先マスタは `book_id` スコープ。役員・従業員・仕入先・顧客などを統一管理する。
+
+## kind の選び方
+
+| kind | 用途 |
+|------|------|
+| `vendor` | 仕入先・外注先・サブスク提供事業者など |
+| `customer` | 顧客 |
+| `director` | 役員(取締役・代表など)。立替経費の立替者になりうる |
+| `employee` | 従業員。立替経費の立替者になりうる |
+| `other` | その他 |
+
+`member_id` で workspace_members に紐付け可能(役員/従業員のみ意味あり)。
+
+## default_payable_account_id
+
+立替記帳時の貸方デフォルト科目。`director`/`employee` の取引先には必ず設定すること。
+
+- 推奨: **liability** 型の「役員借入金」「従業員未払金」など
+- 許容: **equity** 型(運用実態として一部の帳簿で利用されるため)
+- NG: **asset/revenue/expense** 型 → API が `invalid_default_payable_account` で 400 を返す
+
+該当科目が無い場合は先に `POST /api/accounting/accounts` で作成すること。
+
+## エンドポイント
+
+### GET /api/accounting/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
+
+```
+Body:
+  {
+    "name": "山田太郎",
+    "kind": "director",
+    "member_id": null,
+    "default_payable_account_id": "<account uuid>"
+  }
+
+Response 201: { "counterparty": {...} }
+
+エラー:
+  400 invalid_kind                       — kind 不正
+  400 invalid_default_payable_account    — 指定した科目が立替貸方として不適切
+  409 counterparty_name_conflict         — 同名のアクティブな取引先が存在 (context.existing_id 参照)
+```
+
+### GET /api/accounting/counterparties/[id]
+
+```
+Response: { "counterparty": {...} }
+404 counterparty_not_found
+```
+
+### PATCH /api/accounting/counterparties/[id]
+
+```
+Body (全て任意):
+  { "name", "kind", "member_id", "default_payable_account_id", "is_archived" }
+
+Response: { "counterparty": {...} }
+```
+
+### DELETE /api/accounting/counterparties/[id]
+
+ソフト削除(`is_archived=true`)。物理削除はしない(過去仕訳の参照を保持するため)。
+
+```
+エラー:
+  409 has_unsettled_reimbursements — 未精算の立替が残っているとアーカイブ不可
+```
+
+### GET /api/accounting/counterparties/[id]/balance
+
+補助元帳。取引先別の残高(勘定科目別)と明細リスト。
+
+```
+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`。

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

@@ -0,0 +1,120 @@
+# API: 立替経費(Expense Reimbursements)
+
+立替経費は「立替記帳の仕訳」と「精算の仕訳」の対応関係を保持する別レイヤ。両仕訳の line に同じ `counterparty_id` が付与される。
+
+## 仕訳パターン
+
+**立替記帳時:**
+```
+(借) 費用科目                 amount    [counterparty_id=<立替者>]
+  (貸) counterparty.default_payable_account_id   amount    [counterparty_id=<立替者>]
+```
+
+**精算時:**
+```
+(借) counterparty.default_payable_account_id   amount    [counterparty_id=<立替者>]
+  (貸) wallet_account (現金 or 普通預金)         amount    [counterparty_id=<立替者>]
+```
+
+## エンドポイント
+
+### POST /api/accounting/expense-reimbursements
+
+立替経費を記帳する。
+
+```
+Body:
+  {
+    "paid_by_counterparty_id": "<立替者のcounterparty uuid>",
+    "occurred_on": "YYYY-MM-DD",
+    "amount": 1000,
+    "expense_account_id": "<費用科目 uuid>",
+    "description": "新幹線代 東京→大阪",      // 任意
+    "receipt_ids": ["<receipt uuid>"],         // 任意。既存の未添付レシートを紐付ける
+    "category_dimensions": {                   // 任意。一般社団法人プロファイル等で expense 行に
+      "net_asset_restriction": "general"        // ディメンションが必要な場合に指定。expense 行(借方)のみに付与される
+    }
+  }
+
+Response 201: { "reimbursement": { "id", "expense_journal_entry_id" } }
+
+主要エラー:
+  400 invalid_amount                       — amount が正の数値でない
+  400 expense_account_not_found            — 費用科目が見つからない / 別帳簿
+  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 が未設定
+```
+
+### 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 — 立替者の貸方科目が後から消去された場合
+```
+
+### GET /api/accounting/expense-reimbursements
+
+```
+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]
+
+立替記帳の取消(精算前のみ)。関連する立替仕訳も同時に削除される。
+
+```
+エラー:
+  409 already_settled — 精算済みは取消不可
+```
+
+## ベストプラクティス
+
+- 立替者を識別できない場合は推測しない。`GET /counterparties?q=<name>` で検索し、複数候補がある場合は **PMに確認** すること
+- 「立替金」(asset 勘定として存在することがある)は会社が他者のために立て替えた場合の科目。**役員/従業員が立て替えた場合の貸方には使わない** こと
+- 描かれた `next_action` を必ず読む。recover 可能なエラーは指示通りに対処

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

@@ -0,0 +1,100 @@
+# API: 仕訳(Journal Entries)
+
+複式簿記の仕訳エンドポイント。立替経費以外の通常取引(収入/支出/振替/手動仕訳/期首残高)を扱う。
+
+## entry_type の区別
+
+| entry_type | 用途 | buildLines の挙動 |
+|-----------|------|------------------|
+| `income`  | 収入 | (借)wallet / (貸)category(収益) |
+| `expense` | 支出 | (借)category(費用) / (貸)wallet |
+| `transfer` | 振替 | (借)to_account / (貸)from_account |
+| `manual`  | 手動仕訳(複合仕訳) | lines を直接指定 |
+| `opening_balance` | 期首残高 | 専用APIあり(本ドキュメント対象外) |
+
+## エンドポイント
+
+### POST /api/accounting/entries
+
+**シンプル仕訳 (income/expense):**
+```
+{
+  "entry_type": "expense",
+  "entry_date": "2026-05-25",
+  "amount": 1000,
+  "wallet_account_id": "<is_wallet=true の account>",
+  "category_account_id": "<expense 型の account>",
+  "description": "サーバー利用料",
+  "category_dimensions": { "net_asset_restriction": "general" }  // 一般社団法人プロファイル時のみ必要
+}
+```
+
+**振替 (transfer):**
+```
+{
+  "entry_type": "transfer",
+  "entry_date": "2026-05-25",
+  "amount": 50000,
+  "from_account_id": "<wallet account>",
+  "to_account_id": "<wallet account>",
+  "description": "現金→普通預金"
+}
+```
+
+**手動仕訳 (manual) - 複合仕訳が必要なときのみ:**
+```
+{
+  "entry_type": "manual",
+  "entry_date": "2026-05-25",
+  "description": "...",
+  "lines": [
+    { "account_id": "...", "debit": 1000, "credit": 0, "memo": "...", "counterparty_id": "..." },
+    { "account_id": "...", "debit": 0, "credit": 1000, "counterparty_id": "..." }
+  ]
+}
+```
+
+**注意点:**
+- `lines` は **必ず2行以上** で **借方合計=貸方合計** であること(DB triggerで強制される)
+- `counterparty_id` は任意。付与すると補助元帳でその取引先の明細として集計される
+- 一般社団法人プロファイルでは収益/費用行に `dimensions.net_asset_restriction` が必須
+
+```
+Response: { "entry": {...} }
+エラー:
+  400 entry_date and entry_type are required
+  400 at least 2 lines required
+  400 debit/credit must balance
+  409 period_closed
+```
+
+### PATCH /api/accounting/entries/[id]
+
+仕訳の編集。明細は全置換(既存lineを削除して body.lines を挿入)。
+
+```
+締めチェック:
+  - 元の entry_date が締め後 → 409 period_closed (編集不可)
+  - 新しい entry_date が締め後 → 409 (日付変更不可)
+  - opening_balance は編集不可(専用画面から再入力)
+```
+
+### DELETE /api/accounting/entries/[id]
+
+仕訳削除。lines は CASCADE で同時削除。
+
+### GET /api/accounting/entries
+
+```
+Query:
+  ?from=YYYY-MM-DD&to=YYYY-MM-DD
+  ?limit=200
+
+Response: { "entries": [{ ..., lines: [...] }] }
+```
+
+## ベストプラクティス
+
+- **通常の経費は manual で複合仕訳を組まず、`expense` ですませる。** シンプルな分、間違いが少ない
+- **立替経費は仕訳APIで組み立てず、必ず /expense-reimbursements を使う。** 自前で組むと「立替者」軸の集計ができない
+- **dimensions の `net_asset_restriction`** は一般社団法人プロファイル時のみ意味あり。株式会社(corporation-jp)では空でOK

package/skills/accounting-bookkeeping/references/troubleshooting.md

@@ -0,0 +1,117 @@
+# Troubleshooting: 会計API
+
+会計APIで遭遇しやすいエラーパターンと対処。
+
+## エラーレスポンスの構造
+
+```json
+{
+  "error": "missing_default_payable_account",
+  "message": "取引先「山田太郎」に立替用の貸方科目が未設定です",
+  "next_action": "PATCH /api/accounting/counterparties/<id> で...",
+  "context": { "counterparty_id": "..." }
+}
+```
+
+**必ず `next_action` を読み、その指示に従うこと。** 指示が曖昧な場合のみ自己判断する。
+
+## 立替経費まわり
+
+### `missing_default_payable_account` (422)
+
+**原因:** 立替者の `default_payable_account_id` が未設定。
+
+**対処:**
+1. liability 型の科目「役員借入金」「従業員未払金」などがあるか確認
+   - `GET /api/accounting/accounts` で `type=liability` をフィルタ
+2. 無ければ作成: `POST /api/accounting/accounts` で `{ name: "役員借入金", type: "liability" }`
+3. counterparty に紐付け: `PATCH /api/accounting/counterparties/<id>` で `{ default_payable_account_id: "..." }`
+4. 立替記帳をリトライ
+
+### `counterparty_not_found` (404)
+
+**原因:** 立替者の counterparty が未登録。
+
+**対処:**
+1. `GET /api/accounting/counterparties?q=<name>` で typo の可能性を確認
+2. 該当者がいなければ `POST /api/accounting/counterparties` で作成
+   - 役員なら `kind: "director"`、従業員なら `kind: "employee"`
+   - 可能なら `default_payable_account_id` も同時に設定
+
+### `counterparty_name_conflict` (409)
+
+**原因:** 同名のアクティブな取引先が既に存在(本人と判断できない場合がある)。
+
+**対処:**
+- `context.existing_id` が返るので、それが同一人物か確認
+- 同一人物なら既存IDを使う
+- 別人なら名前を変える(例: "山田太郎(役員)" vs "山田太郎(従業員)")
+
+### `already_settled` (409)
+
+**原因:** 精算しようとした立替が既に精算済み。
+
+**対処:** `context.settled_at` と `context.settlement_journal_entry_id` を確認し、二重精算を回避
+
+## 期間まわり
+
+### `period_closed` (409)
+
+**原因:** 指定日付が締め済期間内。
+
+**対処:**
+- 締めはPMの権限。勝手に再オープンしない
+- 締め後の取引なら日付を調整(後日付に変更)、または PM にエスカレーション
+- threadで `mentions: ["role:pm"]` を付けて「<DATE> の取引が締め後だが記帳が必要」と相談
+
+## 科目まわり
+
+### `invalid_expense_account_type` (400)
+
+**原因:** 立替経費の費用科目に expense 型でない科目を指定した。
+
+**対処:** `GET /api/accounting/accounts` で type=expense の科目を取得して使用
+
+### `not_a_wallet_account` (400)
+
+**原因:** 精算時の支払口座に `is_wallet=false` の科目を指定した。
+
+**対処:** `is_wallet=true` の科目(現金/普通預金)を選択
+
+### `invalid_default_payable_account` (400)
+
+**原因:** default_payable_account_id に asset/revenue/expense 型を指定した。
+
+**対処:** liability 型(または equity 型)の科目を指定する。「立替金」(asset)は逆向きなので使わない
+
+## 仕訳整合性
+
+### `at least 2 lines required` / `debit/credit must balance`
+
+**原因:** 手動仕訳の `lines` が壊れている。
+
+**対処:**
+- lines は2行以上必要
+- 借方合計 = 貸方合計 を自前で計算してから POST
+- DB trigger は不整合を必ず検出するので、ローカル検算が大事
+
+## 取引先のアーカイブ
+
+### `has_unsettled_reimbursements` (409)
+
+**原因:** 未精算の立替が残っている取引先をアーカイブしようとした。
+
+**対処:**
+1. `GET /api/accounting/expense-reimbursements?counterparty_id=<id>&settled=false` で未精算リスト取得
+2. 各立替を精算 (`POST /<id>/settle`)
+3. アーカイブを再実行
+
+## 自己解決できない場合
+
+エラーの `next_action` が無い、または指示通り対処しても繰り返し失敗する場合:
+
+1. プロジェクトメモリーで過去事例を検索
+2. なければ `POST /api/threads` でヘルプスレッド起票
+   - `thread_type: "help"`, `mentions: ["role:pm"]`
+   - `attempted_resolution` に試したことを必ず書く
+3. **仕訳を中途半端な状態で残さない。** 失敗した立替記帳は `DELETE /api/accounting/expense-reimbursements/<id>` で取り消してからエスカレーション