addashboard-cli 0.2.4

package/skills/ad-ops/README.md

@@ -0,0 +1,139 @@
+# ad-ops skill (広告運用スキル / Claude Code + Codex CLI 両対応)
+
+ad-dashboard (`https://macchiato.site`) の webgram CLI を Claude Code / Codex CLI から自然言語で操作するためのスキル。「広告運用」「YDA 入稿」等のキーワードで発火し、裏で `webgram` コマンドを `npx` 経由で呼び出す。インストール作業はゼロ (Node.js 18+ が入っていれば OK)。
+
+## 何ができる?
+
+エージェント (Claude Code / Codex) のチャットに次のように打つだけで動く:
+
+- 「広告運用したい」「YDA に PAUSED で入稿して」「Meta のアカウント一覧見せて」
+- 「ad-dashboard のログイン状態は?」「webgram でログアウトして」
+- 「SmartNews に dry-run で入稿して」「TikTok のキャンペーン一覧」
+
+裏で以下を実行:
+
+- 認証状態確認: `webgram auth whoami`
+- アカウント/キャンペーン参照: `webgram list --platform <媒体> --resource <r>`
+- 入稿: `webgram submit --platform <媒体> --json-file <path>` (dry-run 既定、実入稿は `--no-dry-run --yes` 必須)
+
+対応媒体: YDA / Meta / Google / SmartNews / ByteDance の 5 媒体。
+
+## 利用者の初回セットアップ
+
+### 1. Node.js が入っているか確認
+
+```bash
+node --version
+```
+
+`v18.x` 以上が出れば OK。無ければ [nodejs.org](https://nodejs.org) から **LTS 版** をインストール。
+
+### 2. エージェント別の Skill 配置
+
+Skill 本体 (`SKILL.md` / `config.json` / `README.md`) は npm パッケージ `addashboard-cli` に同梱されている。
+
+#### Claude Code の場合
+
+Claude Code のチャットに以下を貼り付けて実行を依頼:
+
+```
+addashboard-cli の ad-ops skill を ~/.claude/skills/ に配置して
+```
+
+Claude が裏で `npm pack addashboard-cli` → 展開 → `cp` を実行する。手動で入れる場合:
+
+```bash
+mkdir -p ~/.claude/skills/ad-ops /tmp/ad-ops-extract
+cd /tmp/ad-ops-extract && npm pack addashboard-cli@latest
+tar xzf addashboard-cli-*.tgz --strip-components=1
+cp -r skills/ad-ops/. ~/.claude/skills/ad-ops/
+```
+
+完了すると `~/.claude/skills/ad-ops/` に `SKILL.md` / `config.json` / `README.md` が配置される。Claude Code を一度終了して開き直す (通常は不要だが認識しない時は再起動)。
+
+#### Codex CLI の場合
+
+Codex CLI には Claude Code 相当の skills 自動発火機能は無いので、以下いずれかで SKILL.md を context に読み込ませる。
+
+**方式 A: プロジェクトルートの `AGENTS.md` に参照を書く (推奨)**
+
+作業ディレクトリの `AGENTS.md` に以下を追記:
+
+```markdown
+## 広告運用 (ad-ops skill)
+
+ad-dashboard の広告操作は `~/.codex/skills/ad-ops/SKILL.md` に従って `webgram` CLI (`npx -y addashboard-cli@latest`) 経由で実行する。設定は `~/.codex/skills/ad-ops/config.json` を参照。
+```
+
+Skill 本体を配置:
+
+```bash
+mkdir -p ~/.codex/skills/ad-ops /tmp/ad-ops-extract
+cd /tmp/ad-ops-extract && npm pack addashboard-cli@latest
+tar xzf addashboard-cli-*.tgz --strip-components=1
+cp -r skills/ad-ops/. ~/.codex/skills/ad-ops/
+```
+
+**方式 B: 都度 `--instructions` で明示読み込み**
+
+```bash
+codex --instructions ~/.codex/skills/ad-ops/SKILL.md "YDA に PAUSED で入稿の dry-run 走らせて"
+```
+
+**方式 C: `~/.codex/config.toml` の `instructions` に恒久追加** (Codex CLI のバージョンによる。詳細は Codex CLI docs 参照)
+
+### 3. 動作確認
+
+エージェントに以下のように投げると発火するはず:
+
+```
+広告運用スキル使える?
+```
+
+Claude Code なら「ad-ops skill が使えます。ad-dashboard のログイン状態を確認しましょうか?」と返り、Codex なら AGENTS.md 経由で SKILL.md の内容に沿って動く。
+
+## 発火方法 (使い方)
+
+エージェントに自然言語で頼むだけ。以下のキーワードのいずれかで発火する:
+
+- **参照系**: 「YDA のアカウント見せて」「Meta のキャンペーン一覧」「広告アカウント一覧」
+- **入稿系**: 「YDA に入稿して」「PAUSED で dry-run」「Meta に入稿の dry-run」
+- **認証系**: 「ad-dashboard のログイン状態は?」「webgram でログアウトして」
+- **直接指定**: 「/ad-ops」「ad-ops skill 使って」「広告運用スキルで」
+
+### 典型フロー (YDA 入稿の例)
+
+1. ユーザー: 「YDA のアカウント一覧見せて」
+2. エージェント: `webgram list --platform yda --resource accounts` を実行 → 一覧を要約して提示
+3. ユーザー: 「桑の葉茶カテキンに PAUSED で dry-run」
+4. エージェント: fixtures/yda_poc.json を雛形に JSON を組み立て → dry-run 実行 → 結果を要約
+5. ユーザー: 「OK、実入稿して」
+6. エージェント: `--no-dry-run --yes` を付けて再実行 → 入稿完了
+
+**ログインが必要な場合はエージェントが代行せず、ユーザーにターミナル実行を依頼する** (パスワードをエージェントに渡さない運用)。
+
+## トラブルシュート
+
+| 症状 | 対処 |
+|---|---|
+| Claude Code が「ad-ops スキル」を認識しない | Claude Code を再起動。`ls ~/.claude/skills/ad-ops/SKILL.md` でファイルがあるか確認 |
+| Codex が SKILL.md の指示に従わない | `AGENTS.md` に SKILL.md への参照が書かれているか確認 / `--instructions` で明示読み込み |
+| `command not found: npx` | Node.js が入っていない。[nodejs.org](https://nodejs.org) から LTS 版をインストール |
+| ログインに失敗する | メール/パスワードを Web UI (`https://macchiato.site`) で確認 |
+| エンドポイントを変えたい | `<skill dir>/config.json` の `endpoint` を編集 (`~/.claude/skills/ad-ops/config.json` or `~/.codex/skills/ad-ops/config.json`) |
+| 入稿 JSON の必須フィールドが分からない | tarball 同梱の `fixtures/README.md` を参照 (全 5 媒体の必須フィールドを集約) |
+
+## バージョン更新
+
+`config.json` の `npmPackage` が `addashboard-cli@latest` になっていれば、`npx -y` が常に最新版を取ってくる (初回のみ DL、以降キャッシュ)。特定バージョンにピン止めしたい場合は `addashboard-cli@0.X.Y` に書き換える。Skill 本体 (`SKILL.md` 等) を新しくしたい場合は、方式 A の手順を再実行するだけで上書きされる。
+
+## 参考ドキュメント
+
+- CLI 本体の README: [cli/README.md](../../README.md) (人間向けの完走マニュアル + AI エージェント向け決定表)
+- 入稿ボディ雛形: [cli/fixtures/README.md](../../fixtures/README.md)
+- freee 請求書発行スキル: [../invoice-issue-freee/SKILL.md](../invoice-issue-freee/SKILL.md)
+
+## 配布元
+
+GitHub Releases: https://github.com/WEBGRAM-WG/ad-dashboard/releases
+(社内 Slack `#alimie-webgram` にも URL を貼っている)

package/skills/ad-ops/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ad-ops
+description: ad-dashboard (https://macchiato.site) の webgram CLI 経由で広告動画を YDA に半自動入稿する (現状 YDA のみ対応、Meta / TikTok は将来対応予定)。議事録 (2026-07-14) 由来の動画入稿フロー (5 ステップ + 固定デフォルト + URL 空き番号自動割当 + 一覧 OK 確認) がメイン用途。「広告運用」「広告入稿」「動画入稿」「まとめ入稿」「ASC 入稿」「YDA 入稿」「Meta 入稿」「TikTok 入稿」「webgram」「ad-dashboard」と言われたら使用。Node.js が入っていれば追加インストール不要 (`npx` 経由)。
+---
+
+# ad-ops skill (広告運用スキル)
+
+Google Drive から手動 DL 済みの動画を各媒体に半自動入稿するためのスキル。**現状 YDA のみ対応**、Meta / TikTok は将来対応予定。
+
+配置・発火方法は同ディレクトリの [README.md](./README.md) 参照。
+
+## 動画入稿フロー (メイン用途)
+
+macOS Finder で「option キー長押し → パス名をコピー」した動画パスを、ユーザーがドラッグ&ドロップで提示するところから始まる半自動ワークフロー。
+
+### Step 0: ログイン状態確認 (メモ)
+
+```bash
+npx -y addashboard-cli@latest auth whoami
+```
+
+* 成功 → 1 行要約して次へ
+
+* `not_logged_in` → 「ターミナルで `npx -y addashboard-cli@latest auth login` を実行してください」と提示して停止。エージェントは代行しない (Google SSO のブラウザ操作は本人が行う)
+
+### Step 1: 動画ファイルパスの受け取り
+
+* ユーザーが動画ファイルの絶対パスを **ドラッグ&ドロップ** で提示 (1 本〜複数本、本数指定なしで OK)
+
+* パスが未指定なら AskUserQuestion で提示を促す
+
+* パスの存在確認: `ls -l <path>` で読める形式かチェック (mp4 等)
+
+### Step 2: 入稿モードの判定
+
+`新規` / `既存 (ASC 等まとめ入稿)` のどちらかをユーザー指示から判定。指示が無ければ AskUserQuestion で確認する。
+
+| モード      | 構成                                         | 予算デフォルト            |
+| -------- | ------------------------------------------ | ------------------ |
+| 新規       | 1 キャンペーン = 1 広告セット = 1 広告 (動画本数 = キャンペーン数) | 12,000 円/日         |
+| 既存 (ASC) | 1 キャンペーン内に複数広告をまとめる。アルゴリズムが好調クリエイティブに配信寄せ  | 5 万〜10 万円/日 (人により) |
+
+### Step 3: パラメータ収集
+
+**固定デフォルト値** (指定が無ければこれで進める):
+
+* アトリビューション計測期間: **1 日** (デフォルト 7 日を毎回 1 日に変更する慣習)
+
+* CTA ボタン: **詳細を見る**
+
+* 入札戦略: **tCPA 8,500 円** (ターゲット CPA)
+
+* 予算: 新規 = 12,000 円、ASC = 50,000〜100,000 円
+
+**必ずユーザー確認 or 自動生成が必要な項目**:
+
+* **入稿先アカウント名**: アカウント名で指定可 (アカウント ID は不要、CLI 側で名前 → ID 解決)。指定なければ AskUserQuestion で聞く
+
+* **入稿リンク (URL 末尾番号)**: 既存アカウントの入稿履歴から使用済み番号を取得し、**未使用の空き番号を自動割当**
+
+  * 連番でなくて OK。被らないことだけ守る (例: 1〜50 が使用中なら 51 以降、または途中の 7 が未使用なら 7)
+
+  * ベース URL は案件ごとに固定 (Bit.ly 系ドメイン等)。末尾パラメータ番号のみ可変
+
+  * 案件ごとの URL 一覧はシート管理されているので、そこから引く運用も可
+
+* **キャンペーン名**: `{空き番号}_{クリエイティブ名}_{YYYY-MM-DD}` で自動生成
+
+* **配信戦略**: `最大配信` / `tCPA (8,500 円)` の 2 択。指定なければデフォルト tCPA
+
+### Step 4: 一覧提示 → OK 確認 (必須)
+
+動画本数ぶんの入稿リストを **表形式で提示** し、必ず AskUserQuestion で OK 確認を取る。**OK が取れるまで Step 5 に進まない。**
+
+| # | 媒体  | 動画ファイル名      | キャンペーン名                  | 入稿リンク               | 予算     | 配信戦略       |
+| - | --- | ------------ | ------------------------ | ------------------- | ------ | ---------- |
+| 1 | YDA | video\_A.mp4 | 07\_video\_A\_2026-07-16 | <https://.../?p=07> | 12,000 | tCPA 8,500 |
+| 2 | YDA | video\_B.mp4 | 08\_video\_B\_2026-07-16 | <https://.../?p=08> | 12,000 | tCPA 8,500 |
+
+URL 番号・予算・配信戦略に不満があれば Step 3 に戻ってパラメータを差し替える。
+
+### Step 5: 順次実行
+
+OK 後、リスト順に CLI で入稿する:
+
+```bash
+npx -y addashboard-cli@latest submit \
+  --platform <yda|meta|tiktok> \
+  --account "<アカウント名>" \
+  --video <動画パス> \
+  --campaign-name "<キャンペーン名>" \
+  --url "<入稿リンク>" \
+  --budget 12000 \
+  --bid-strategy tcpa \
+  --tcpa 8500 \
+  --attribution-days 1 \
+  --cta detail
+```
+
+* 1 本ごとに成功/失敗を報告
+
+* 途中失敗は握りつぶさず、残りを続行するか AskUserQuestion で確認
+
+* 完了後、キャンペーン ID / 広告 ID の一覧を要約表示
+
+### Step 6: 管理画面 URL を開く
+
+入稿完了後、対象媒体の管理画面 (該当キャンペーンの詳細ページ) を **`open <URL>`** **で開く**。ユーザーが目視で入稿結果を確認できるようにする。
+
+* YDA: `https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&campaignId=<campaignId>` (キャンペーン ID は Step 5 の応答から取得)
+
+* Meta / TikTok は将来対応時に URL 形式を追記
+
+* 複数入稿した場合は、キャンペーン一覧ページ (`https://ads-display.yahoo.co.jp/campaign/list?accountId=<accountId>`) を 1 つ開けば十分
+
+```bash
+open "https://ads-display.yahoo.co.jp/campaign/detail?accountId=<accountId>&campaignId=<campaignId>"
+```
+
+## 媒体別の注意
+
+**現状の動画入稿対応: YDA のみ。** Meta / TikTok を指定された場合は「現状未対応、YDA のみ」と明示してから相談する。
+
+| 媒体                     | 動画入稿対応   | 入稿リンクの粒度               | 備考                                             |
+| ---------------------- | -------- | ---------------------- | ---------------------------------------------- |
+| **YDA**                | ✅ 対応済み   | 広告ごと                   | まず YDA から対応 (社内優先順位、名倉さん依頼)                    |
+| **Meta**               | ⏳ 将来対応予定 | 広告ごと (まとめ入稿でも広告単位で変わる) | ASC でも広告ごとに個別リンクを設定                            |
+| **TikTok / ByteDance** | ⏳ 将来対応予定 | 広告グループ単位で 1 本          | まとめ入稿は 10 本でも 20 本でも入稿リンクは 1 つ (クリエイティブグループ単位) |
+
+***
+
+## 備考: その他のコマンド
+
+動画入稿フロー以外に CLI が受け付ける主なコマンド。詳細は [cli/README.md](../../README.md) と [cli/fixtures/README.md](../../fixtures/README.md) 参照。
+
+| 用途                  | コマンド                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| ログイン状態確認            | `npx -y addashboard-cli@latest auth whoami`                                                                   |
+| ログアウト               | `npx -y addashboard-cli@latest auth logout`                                                                   |
+| ヘルプ                 | `npx -y addashboard-cli@latest --help`                                                                        |
+| アカウント一覧             | `npx -y addashboard-cli@latest list --platform <yda\|meta\|google\|smartnews\|bytedance> --resource accounts` |
+| キャンペーン一覧            | `npx -y addashboard-cli@latest list --platform <媒体> --resource campaigns --account-id <id>`                   |
+| 汎用入稿 (JSON) dry-run | `npx -y addashboard-cli@latest submit --platform <媒体> --json-file <path>`                                     |
+| 汎用入稿 (JSON) 実入稿     | `npx -y addashboard-cli@latest submit --platform <媒体> --json-file <path> --no-dry-run --yes`                  |
+
+汎用入稿 (JSON ボディ直渡し) は yda / meta / google / smartnews / bytedance の 5 媒体対応。fixtures の雛形は tarball 同梱の `fixtures/*_poc.json`、各媒体の必須フィールドは `fixtures/README.md`。

package/skills/ad-ops/config.json

@@ -0,0 +1,5 @@
+{
+  "npmPackage": "addashboard-cli@latest",
+  "endpoint": "https://macchiato.site",
+  "_comment": "CLI は npm public registry (addashboard-cli) から `npx -y` 経由で実行する。endpoint はローカル開発時 http://localhost:3001 に変更可"
+}

package/skills/invoice-issue-freee/README.md

@@ -0,0 +1,109 @@
+# invoice-issue-freee skill (Claude Code 用)
+
+WEBGRAM様の入金(クライアント売上請求)を、ad-dashboard の `webgram` CLI 経由で freee 発行 → PDF保存 → Google Drive格納・請求書管理シート記入・Gmail下書きまで自動化するスキル。
+
+**発行権限**: サーバー側 allowlist で管理 (未登録emailは 403 forbidden)。追加は運用担当者へ依頼。
+
+## 何ができる？
+
+Claude Code のチャットに次のように打つだけで動きます:
+
+- 「freee で請求書出して」
+- 「テスト御中の請求書ドラフト作って(¥300,000/広告運用代行費)」
+- 「請求書のログイン状態確認」
+
+裏で Claude が:
+1. `webgram freee issue` で請求書を発行 (freee)
+2. `report_url` から PDF を取得 (`biz-agent-data/out/YYYYMMDD_会社名.pdf` として保存)
+3. Google Drive の月別/入金/カテゴリ配下に PDF を格納
+4. 請求書管理シートに1行追記 (ステータス=確認待ち)
+5. Gmail 下書きを作成 (Drive リンクを本文埋込)
+6. Drive / シート / Gmail 下書きの3タブを `open` で表示 → 目視確認
+
+## 利用者の初回セットアップ
+
+### 1. Node.js が入っているか確認
+
+```bash
+node --version
+```
+`v18.x` 以上が出ればOK。
+
+### 2. `gws` CLI がインストール済みかつ請求書管理シート/Driveにアクセスできるアカウントで認証済み
+
+```bash
+gws auth status
+```
+
+`user:` が該当アカウントで表示されればOK。未認証なら:
+
+```bash
+gws auth login  # ブラウザで該当アカウントを選択
+```
+
+### 3. Claude Code に **npm パッケージからスキルを展開してもらう**
+
+Claude Code のチャットに次のように貼り付け:
+
+```
+npm の addashboard-cli パッケージから invoice-issue-freee skill を ~/.claude/skills/ に展開して
+```
+
+Claude が裏で次のコマンドを実行します:
+
+```bash
+mkdir -p ~/.claude/skills/invoice-issue-freee
+npm pack addashboard-cli@latest --pack-destination /tmp
+tar xzf /tmp/addashboard-cli-*.tgz -C /tmp --strip-components=1
+cp -r /tmp/skills/invoice-issue-freee/. ~/.claude/skills/invoice-issue-freee/
+```
+
+完了すると `~/.claude/skills/invoice-issue-freee/` に SKILL.md / config.json / README.md が配置されます。
+
+### 4. Claude Code を再起動
+
+新しいスキルを認識させるため、Claude Code を一度終了して開き直す。
+
+## 使い方
+
+Claude Code に自然言語で頼むだけ:
+
+```
+> freee で テスト御中に ¥300,000 の広告運用代行費 で請求書出して
+```
+
+Claude が発行内容を確認 → dry-run → 本発行の同意 → PDF保存 → Drive/Sheet/Gmail → 目視URLを開く の順で進めます。
+
+## 設定変更
+
+### エンドポイントを変えたい
+
+`~/.claude/skills/invoice-issue-freee/config.json` の `endpoint`:
+- 本番: `https://macchiato.site` (デフォルト)
+- ローカル開発: `http://localhost:3001`
+
+### 本番用の Drive フォルダ / シートを使いたい (テスト用IDから切替)
+
+`config.json` の `freee.drive.parentFolderId` と `freee.sheet.spreadsheetId` を本番IDに差し替え。
+
+デフォルトはプレースホルダ (`REPLACE_ME_DRIVE_FOLDER_ID` / `REPLACE_ME_SPREADSHEET_ID`) が入っているので、初回セットアップ時に必ず自環境の値に差し替えてください。
+
+## トラブルシュート
+
+| 症状 | 対処 |
+|---|---|
+| Claude が「invoice-issue-freee スキル」を認識しない | Claude Code を再起動。`ls ~/.claude/skills/invoice-issue-freee/SKILL.md` でファイルがあるか確認 |
+| `403 forbidden` (freee issue時) | サーバー側 allowlist 未登録 email でログインしている。運用担当者に allowlist 追加を依頼 or 登録済み email で `auth login` |
+| `unauthorized` (freee templates時) | freee 未認可。`webgram freee login` を実行してブラウザで許可 |
+| `deduped: true` で新規発行にならない | 同一 body_hash がキャッシュされている。description or billingDate を微修正 |
+| Drive/Sheet が 403/404 | gws CLI が別アカウントの token を使っている。`gws auth logout` → `gws auth login` |
+| Gmail 下書きが空になる | RAW MIME の Python heredoc に日本語コメントを混ぜている。SKILL.md の base64url encode 手順を参照 |
+| PDF ダウンロードで座標クリックが複製ページに遷移 | メニュー座標が動的。`read_page interactive` で「PDFダウンロード」ref を取得してからクリック |
+
+## バージョン更新
+
+CLI 本体 (`addashboard-cli`) は `config.json` で `@latest` 指定のため、`npx` 実行のたびに自動更新されます。スキル定義 (SKILL.md / config.json) だけを最新化したい場合は、上記「初回セットアップ」の手順3を再実行してください。
+
+## 配布元
+
+npm public registry: https://www.npmjs.com/package/addashboard-cli

package/skills/invoice-issue-freee/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: invoice-issue-freee
+description: WEBGRAM様の入金(クライアント売上請求)を ad-dashboard の webgram CLI 経由で freee 発行し、report_url からPDF保存 → Drive格納・請求書管理シート記入・メール下書きまで行う。「請求書発行」「freee請求書」「請求書作成」「売上請求」「invoice発行」と言われたら使用。
+---
+
+# invoice-issue-freee skill (ad-dashboard CLI 配布版)
+
+WEBGRAM様の**入金サイクル（クライアントへの売上請求）専用**スキル。webgram CLI (`webgram freee` 系サブコマンド) をラップして、freee 発行 → PDF保存 → Drive/Sheet/Gmail後続まで一気通貫で行う。
+
+**発行権限はサーバー側 allowlist で管理**(未登録emailは 403 forbidden)。請求書送信担当者は最終目視のみで、確認後にシートのステータスを「送信待ち」に更新して送信する。
+
+## 発火条件
+
+- 「請求書発行」「freee請求書」「請求書作成」
+- 「売上請求」「クライアント請求」「invoice発行」
+- 「請求書を出して」「請求書ドラフト」（入金・クライアント文脈）
+
+ASP/メディアへの**出金（支払）は対象外**。
+
+## 前提
+
+- Node.js 18+ が入っていること (webgram CLI が `npx` 経由で動く)
+- `gws` CLI が請求書管理シート/Driveにアクセス可能なアカウントで認証済み (`gws auth status` で確認)
+- サーバー側 allowlist に登録された email で webgram CLI にログイン済み or ログイン可能
+
+## 実行手順（毎回）
+
+### 0. config.json 読込 (最初に必ず)
+
+このスキルディレクトリの `config.json` を Read して以下を取得:
+
+```json
+{
+  "npmPackage": "addashboard-cli@latest",
+  "endpoint": "https://macchiato.site",
+  "freee": {
+    "companyId": 0,
+    "templateId": 0,
+    "drive": { "parentFolderId": "REPLACE_ME_DRIVE_FOLDER_ID", ... },
+    "sheet": { "spreadsheetId": "REPLACE_ME_SPREADSHEET_ID", ... }
+  }
+}
+```
+
+以降 `WEBGRAM_ENDPOINT=<endpoint> npx -y addashboard-cli@latest freee <sub>` で CLI 呼び出す。
+
+### 1. ログイン確認 → 必要なら auth login / freee login
+
+```bash
+WEBGRAM_ENDPOINT=<endpoint> npx -y addashboard-cli@latest auth whoami
+```
+
+- `not_logged_in` の場合: AskUserQuestion で email を取得(サーバー側 allowlist に登録されているもの)、パスワードは **stdin パイプ**で渡す:
+  ```bash
+  printf '%s\n' '<pw>' | WEBGRAM_ENDPOINT=<endpoint> npx -y addashboard-cli@latest auth login --email <email>
+  ```
+- freee 認可されているか確認するには `webgram freee templates` を叩く。`unauthorized` 等が返れば:
+  ```bash
+  WEBGRAM_ENDPOINT=<endpoint> npx -y addashboard-cli@latest freee login
+  ```
+  → ブラウザで freee 認可(人が実施)→ `✓ freee 接続完了 (company_id=...)` を確認
+
+### 2. AskUserQuestion で発行内容を集める
+
+- `partnerDisplayName` (取引先の表示名、例: `テスト`)
+- `partnerId` (freee 取引先ID、`https://settings.secure.freee.co.jp/partners/<ID>` の末尾数字)
+- `billingDate` (請求日、YYYY-MM-DD)
+- `担当` (発行者の名前)
+- `期日` (振込期限、YYYY-MM-DD)
+- `カテゴリ` (代理店ASP / 業務委託 / サービス)
+- `lines[]`: `description` / `quantity` / `unitPrice` / `taxRate`
+
+`templateId` は `config.json.freee.templateId` 固定。
+
+### 3. dry-run → 本発行
+
+```bash
+# invoice.json を組み立てて一時ファイルに保存
+cat > /tmp/invoice.json <<'JSON'
+{ "partnerId": ..., "partnerDisplayName": "...", "billingDate": "...", "templateId": <config.json.freee.templateId>, "lines": [...] }
+JSON
+
+# dry-run
+WEBGRAM_ENDPOINT=<endpoint> npx -y addashboard-cli@latest freee issue --json-file /tmp/invoice.json
+
+# ユーザー確認後、本発行
+WEBGRAM_ENDPOINT=<endpoint> npx -y addashboard-cli@latest freee issue --json-file /tmp/invoice.json --no-dry-run --yes
+```
+
+- 返却: `{ "invoiceId": <id>, "reportUrl": "https://invoice.secure.freee.co.jp/reports/invoices/<id>?from_public=true" }`
+- **dedup機能(body_hashキャッシュ)**: 同一内容の再発行は既存 invoiceId を `deduped:true` で返す。取消後に同じpayloadで再発行するには description や billingDate を微修正して body_hash を変える必要あり
+
+### 4. PDF を保存（report_url → PDF）
+
+freee 請求書 API に PDF DL エンドポイントは無い。`report_url` の freee 帳票ページから PDF を取得する。
+
+**Claude in Chrome で**:
+1. `report_url` を開く
+2. `read_page interactive` で「その他 ▼」→「**PDFダウンロード**」のrefを取得してクリック(座標決め打ちは複製ページに遷移するリスクあり)
+3. ダウンロードされた PDF を `biz-agent-data/out/YYYYMMDD_会社名_INV-XXXXXXXXXX.pdf` にリネーム保存
+
+**macOSダイアログfallback**(自動化から押せない環境):
+1. 別プロセスでwatcher起動:
+   ```bash
+   (while sleep 0.5; do f=$(ls -t ~/Downloads/.com.google.Chrome.* 2>/dev/null | head -1); [ -n "$f" ] && head -c 4 "$f" | grep -q "%PDF" && cp "$f" out/正規名.pdf && break; done) &
+   ```
+2. PDFダウンロードクリック後、watcher が完成一時ファイル(`~/Downloads/.com.google.Chrome.*` 先頭 `%PDF-`)を検知して cp
+3. 完了後 watcher プロセスを kill、`~/Downloads/.com.google.Chrome.*` を削除
+
+### 5. gws後続 (Drive/Sheet/Gmail)
+
+`config.json.freee.drive` / `config.json.freee.sheet` の値を使う。
+
+**Drive PDF格納**:
+- 格納先: `parentFolderId` 配下の `YYYY-MM/入金/{カテゴリ}/`
+- 無ければ `gws drive files.create mimeType=application/vnd.google-apps.folder` で作成
+- PDF upload:
+  ```bash
+  gws drive files create --params '{"uploadType":"multipart","fields":"id,name,webViewLink"}' \
+    --json '{"name":"<file名>","parents":["<folderId>"],"mimeType":"application/pdf"}' \
+    --upload <PDFパス>
+  ```
+- 返却された `webViewLink` を保持
+
+**シート append**:
+- タブ命名: `tabPattern` の `{YY.M}` を発行月に置換 (例 `【改訂版】請求(入金)26.7`)
+- タブが無ければ `templateTabGid` を `duplicateSheet` で複製し、既存データを `values.clear` してからスタート
+- ヘッダー行 (`headerRow=1`) を `values.get` で読み、`config.json.freee.sheet.columns` で列位置を決定 (**ヘッダー名で列解決 = 固定順で詰めない**)
+- 1行 append (valueInputOption=USER_ENTERED):
+  ```json
+  ["<会社名>", <金額>, "<webViewLink>", "<担当>", "確認待ち", "<メモ>", "<期日>"]
+  ```
+
+**Gmail下書き** (`gws gmail users.drafts.create` RAW MIME、添付非対応):
+- 宛先: 請求書送信担当者(本番) or 発行者自身(テスト)
+- 件名: `【<月>】<会社名> 請求書ドラフト`
+- 本文: 挨拶 + 金額サマリ + `webViewLink` を本文埋込
+- Python3 で base64url encode:
+  ```python
+  import base64
+  subject_b64 = base64.b64encode(subject.encode('utf-8')).decode()
+  mime = f'From: <me>\nTo: <to>\nSubject: =?utf-8?B?{subject_b64}?=\nContent-Type: text/plain; charset=UTF-8\nMIME-Version: 1.0\n\n{body}'
+  raw = base64.urlsafe_b64encode(mime.encode('utf-8')).decode().rstrip('=')
+  ```
+
+### 6. 【必須】成果物3つをブラウザで open
+
+```bash
+open "https://drive.google.com/drive/folders/<格納先folderId>"
+open "https://docs.google.com/spreadsheets/d/<sheetId>/edit?gid=<tabGid>"
+open "https://mail.google.com/mail/u/0/#drafts"
+```
+
+**Claude in Chrome の `navigate` ではなく macOSの `open` コマンド**でデフォルトブラウザ(既に該当アカウントでログイン済み)を使う。Claude in Chrome の別プロファイルで開くとログイン状態が異なりアクセス不可になる。
+
+### 7. 請求書送信担当者に通知 (本番運用時)
+
+`message-send` スキル経由で送信担当者に Slack/メール通知。担当者が目視 → シートステータスを「送信待ち」→ 送信。
+
+## 自然言語 → コマンドマッピング
+
+| ユーザー指示 | 実行 |
+|---|---|
+| 「請求書出して」「請求書ドラフト」 | Step 2 で発行内容ヒアリング → Step 3 dry-run → 本発行 → Step 4-6 通し |
+| 「請求書のログイン確認」 | Step 1 whoami + `freee templates` |
+| 「freeeログインして」 | `webgram freee login` (ブラウザ認可) |
+
+## ハマりどころ
+
+- **allowlist**: `webgram freee` の発行権限はサーバー側 allowlist (email) で制限。追加は運用担当者へ依頼(バックエンド env `FREEE_ALLOWED_EMAILS` または middleware コード側)。CLIログイン自体は誰でも可
+- **CSRF**: `/api/freee` は CLI 専用 (Bearer 認証) で CSRF skip 済。ブラウザ Cookie のみのアクセスは 401
+- **PDF DL エンドポイント無し**: 発行は API だが PDF 実体は report_url からのみ (Step 4)
+- **partner_id 必須**: `partner_display_name` だけでは 400。使用停止の取引先でも `partner_display_name` 指定で発行自体は通る (宛名は表示名が使われる)
+- **partners一覧CLIなし**: 現状 partnerId は freee UIから目視取得。Issue #62 で追加提案中
+- **dedup機能**: 同一 body_hash は再発行されず既存 invoiceId が返る。取消後の再発行は payload微修正必要
+- **access_token 6h 失効**: refresh_token で backend が自動更新。refresh 期限切れ時のみ `webgram freee login` を再実行
+- **本番/ローカル切替**: `WEBGRAM_ENDPOINT`(本番 `https://macchiato.site` / ローカル `http://localhost:3001`)
+- **請求書番号**: freee が自動採番 (例 `INV-0000000002`)
+- **CLI呼び出しは `webgram <cmd>` or `npx -y addashboard-cli@latest <cmd>`**: `node .../cli/dist/index.js <cmd>` のようなdist直実行は禁止
+- **auth login の password**: `--password` argv は `ps` 露出リスク。**stdin パイプ**で渡す (`printf '%s\n' '<pw>' | ... auth login --email <email>`)
+- **gws token cache不整合**: 別Googleアカウントを使ってた場合、`gws auth login` で切り替えても `files list` が旧アカウント所有ファイルを返すことがある。**`gws auth logout` → `gws auth login` の再ログインでキャッシュクリア必要**
+
+## 関連スキル / ルール
+
+- ad-dashboard `webgram` skill (同じ配布方式)
+- `webgram freee` コマンド (`cli/src/commands/freee.ts`)、`~/Documents/addashboard/CLAUDE.md`
+- `gws` (Drive/Sheets/Gmail下書きの CLI)
+- `message-send` (請求書送信担当者への通知)
+- WEBGRAM様版 `invoice-issue-freee` (旧Python版・原典の詳細仕様)
+- ルール: `~/.claude/rules/credential-storage-pattern.md`, プロジェクトCLAUDE.md「認証情報の二層構造」

package/skills/invoice-issue-freee/config.json

@@ -0,0 +1,31 @@
+{
+  "npmPackage": "addashboard-cli@latest",
+  "endpoint": "https://macchiato.site",
+  "freee": {
+    "companyId": 0,
+    "templateId": 0,
+    "drive": {
+      "parentFolderId": "REPLACE_ME_DRIVE_FOLDER_ID",
+      "parentFolderName": "REPLACE_ME_請求書フォルダ名",
+      "monthPathPattern": "YYYY-MM/入金/{カテゴリ}"
+    },
+    "sheet": {
+      "spreadsheetId": "REPLACE_ME_SPREADSHEET_ID",
+      "sheetName": "REPLACE_ME_請求書管理シート名",
+      "tabPattern": "REPLACE_ME_タブ名パターン_{YY.M}",
+      "templateTabGid": 0,
+      "headerRow": 1,
+      "columns": {
+        "会社名": "A",
+        "金額": "B",
+        "請求書のリンク": "C",
+        "担当": "D",
+        "ステータス": "E",
+        "メモ": "F",
+        "期日": "G"
+      },
+      "statusInitial": "確認待ち"
+    }
+  },
+  "_comment": "CLI は npm public registry (addashboard-cli) から `npx -y` 経由で実行する。REPLACE_ME_* および 0 のフィールドは利用環境ごとに ~/.claude/skills/invoice-issue-freee/config.json を上書きして自分の freee company / Google Drive / Sheet の値に差し替える"
+}