narrative-lion

Narrative Lion

すべての API 操作には、${CLAUDE_PLUGIN_ROOT}/scripts/nl.py の CLI を使用します。Bash から実行してください：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py <command> [args...] [--json]

認証

export NLK_API_KEY=nlk_xxxxxxxx

https://narrativelion.com/settings/api-keys で作成してください（Pro プランが必要です）。

すべての API 呼び出しでは、Authorization: Bearer $NLK_API_KEY ヘッダーを使用します。

CLI リファレンス

一般

コマンド	説明
nl.py search <query> [--collection ID]	セマンティック検索
nl.py fts <query> [--collection ID]	全文キーワード検索
nl.py collections	すべてのコレクションを一覧表示（二階層のフォルダーツリーと ID）
nl.py notes list [--collection ID] [--type T] [--uncategorized] [--starred]	ノートを閲覧
nl.py notes get <noteId>	ノートの詳細
nl.py transcript <noteId>	動画ノートのトランスクリプト（タイムスタンプ付きセグメント。生のセグメントは --json を指定）
nl.py notes create --type T --content C [--file path] [--skip-ai]	ノートを作成
nl.py submit <video-url> [--wait] [--timeout SECONDS]	YouTube／TikTok の URL から動画ノートを作成（クレジットを消費。冪等）
nl.py job <jobId>	送信したジョブのステータスを確認（完了時にノート ID を取得）
nl.py jobs	保留中のジョブを一覧表示
nl.py export <noteId> [noteId2 ...]	Markdown ZIP としてエクスポート
nl.py usage	クレジット使用量

映画監督

コマンド	説明
nl.py director <concept> [--type T] [--duration N] [--aspect R] [--style S]	コンセプトからストーリーボードを生成（1～2 クレジットを消費）
nl.py director-persist <threadId> --storyboard <md> --instruction <text>	ストーリーボードを映像作品ノートとして保存（LLM コストなし）

Filmwork

コマンド	説明
nl.py overview <noteId>	プロジェクトの概要：ステータス別の件数とすべてのショット
nl.py shot <noteId> <label>	ショットの詳細：事前チェック、アセット、ロール、プロンプト
nl.py shot-create <noteId> --label L [--duration N] [--after LABEL] [--status S]	既存のフィルムワークにショットを作成（クレジット不要）
nl.py shot-delete <shotId>	ショットを削除（論理削除、決定を自動記録）
nl.py preflight <noteId> <label>	事前チェックのみ
nl.py upload <shotId> <assetType> <file> [--label L] [--method M --model M --prompt P --user-note N --parent JSON]	アセットをアップロード（3 ステップのフローに対応、出所情報は任意）
nl.py upload-roll <shotId> <file> [--seed N --model M --prompt-version N]	ロール動画をアップロード
nl.py shot-update <shotId> [--status S] [--blocker JSON] [--prompts JSON] [--dialogue JSON] [--direction JSON] [--model-config JSON] [--relations JSON] [--duration N]	ショットのステータスや各フィールドを更新
nl.py score <rollId> --face N --expr N --motion N --stability N --style N	ロールを採点（重み付き合計を自動計算）
nl.py verdict <rollId> <approved|rejected>	ロールの判定を設定
nl.py golden-roll <rollId>	ゴールデンロールを設定
nl.py decision <noteId> [--shot ID] --action A --reason R --outcome O	決定を記録
nl.py insight <noteId> --category C --tags T1,T2 --title T --detail D [--source-shots JSON]	洞察を記録
nl.py decisions <noteId> [--shot ID] [--limit N] [--offset N]	決定を一覧表示
nl.py insights [noteId] [--category C] [--tag T] [--limit N] [--offset N]	洞察を一覧表示（noteId がない場合は複数のノートを対象）
nl.py prompt <noteId> <shotLabel> [--version N]	プロンプトのバージョンを一覧表示、または指定バージョンのプロンプト全文を表示
nl.py prompt-diff <noteId> <shotLabel> --from N --to M	2 つのプロンプトバージョン間の統合差分
nl.py roll-diff <rollId-A> <rollId-B>	2 つのロールを比較：メタデータ、プロンプト、入力、スコア
nl.py provenance <assetId>	アセットの作成方法を照会
nl.py lineage <assetId> [--depth N]	系譜 DAG 全体を照会（親から子への方向を表示）
nl.py roll-snapshot <rollId>	ロールの生成に使用されたアセットのバージョン
nl.py roll-context <rollId>	ロールを 1 回でデバッグ：プロンプト、入力、出所情報
nl.py set-provenance <assetId> --method M [--model M] [--prompt P] [--parent JSON ...]	作成後に出所情報を設定・更新
nl.py download <assetId> <output_path>	単一のアセットをローカルファイルにダウンロード
nl.py download-shot <noteId> <label> [--dir D] [--all]	ショットのゴールデンアセットをダウンロード（--all ですべてのバージョンを対象）

すべてのコマンドで、生の JSON 出力に --json を使用できます。

注： upload と upload-roll には、ラベルではなくショットの UUID（id フィールド）を指定します。UUID は nl.py shot <noteId> <label> で取得してください。

ベストプラクティス

検索

search はセマンティック検索で、タイトルが一致しない場合も結果を見つけます。 fts はキーワードの完全一致検索です。どちらも --collection を指定できます。

コレクション

2 階層のフォルダーツリーです。collections で全フォルダーとその ID を一覧表示し、notes list --collection ID でコレクションを絞り込みます。 notes list --uncategorized は、どのコレクションにも属していないノートを返します。

送信（動画 URL -> ノート）

submit は動画からノートを作成するパイプライン（文字起こし + AI ノート）を実行します。jobs:submit API キーのスコープが必要で、新しい動画ごとにクレジットがかかります。

• 冪等性：ノートがすでに存在する場合（論理削除済みの場合も含む）、既存のノート ID を返し、料金は発生しません。安全に再実行できます。
• 一括処理のパターン：まずすべての URL を送信し（高速で、--wait は指定しません）、次に nl.py jobs で空になるまでポーリングし、その後 nl.py job <jobId> または notes list で ID を取得します。
• 単一 URL：ノートの準備ができるまで待機するには --wait を使用します（5 秒ごとにポーリングし、デフォルトのタイムアウトは 600 秒です）。
• レート制限：アカウントあたり 1 分間に 10 件まで送信できます。

チャット / SSE

映画監督ノート

director の呼び出しには1～2クレジットかかります。

スレッド：新しい会話を始める場合は --thread を省略し、続ける場合は --thread <id> を指定します。

完全なドキュメント： https://narrativelion.com/docs/film-director

リールコーチ

ユーザーのノートライブラリから、制作にすぐ使える短尺動画スクリプト（TikTok / Reels / Shorts）を生成します。AI が関連するノートを取得し、タイミング付きのショットごとのスクリプトを作成した後、出典となる文章を正確に引用した「コーチノート」で草稿に注釈を付けます。

生成（1～2クレジット）：

curl -N https://narrativelion.com/api/chat/stream \
  -H "Authorization: Bearer $NLK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: NLSkill/1.0" \
  -d '{
    "threadId": "'$(python3 -c 'import uuid; print(uuid.uuid4())')'",
    "actionId": "'$(python3 -c 'import uuid; print(uuid.uuid4())')'",
    "event": {
      "type": "user_text",
      "payload": {
        "text": "Generate a reel script",
        "activeTool": "reel_coach",
        "reelCoachTopic": "Topic or creative brief",
        "reelCoachTargetDurationSec": 30,
        "reelCoachPinnedNoteIds": ["note-id-1"],
        "reelCoachAutoRetrieve": true
      }
    }
  }'

ペイロードのフィールド：

• reelCoachTopic（string）— トピック／概要。最大2000文字。省略した場合は text が使用されます。
• reelCoachTargetDurationSec（number）— 目標尺。最大120秒、デフォルトは30秒です。
• reelCoachPinnedNoteIds（string[]）— 常に含めるノート ID（最大20件）。
• reelCoachAutoRetrieve（boolean）— 関連するノートを自動取得します。デフォルトは true です。

SSE ストリームでは token イベントが送信され、その後、次のアーティファクトを含む complete イベントが送信されます。

• reelCoachSetup — 解決済みの設定（調整／永続化する際に渡します）。
• reelCoachAnnotations — コーチノート：{ draftExcerpt, rationale, confidence, references[] }。
• reelCoachStats — { totalBreakdownCount, usedSourceCount, validatedQuoteCount }。

finalMessage は JSON 形式の草稿です：

{
  "shots": [
    { "title": "Hook", "durationSec": 5, "script": "Spoken text..." },
    { "title": "Core insight", "durationSec": 10, "script": "..." }
  ],
  "coachOverview": "Strategy summary...",
  "sourceRelevance": [{ "noteTitle": "...", "relevanceScore": 0.9 }]
}

Filmwork プロジェクトとして永続化（0クレジット）：

curl -X POST https://narrativelion.com/api/filmwork/director/persist \
  -H "Authorization: Bearer $NLK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: NLSkill/1.0" \
  -d '{
    "shots": [{"title":"Hook","durationSec":5,"script":"..."}],
    "setup": {"topic":"...","targetDurationSec":30,"pinnedNoteIds":[],"autoRetrieve":true},
    "coachOverview": "..."
  }'

{ noteId, title } を返します。永続化した後は、nl.py overview / nl.py shot でプロジェクトを管理します。

調整（任意、1回あたり1クレジット）：

• 提案：{ draft, setup } を指定して POST /api/filmwork/coach/refine-suggestions → { suggestions: [{ label, prompt }] }
• 修正：{ currentDraft, setup, refinementPrompt, pinnedNoteIds? } を指定して POST /api/filmwork/coach/refine（SSE）

完全なドキュメント： https://narrativelion.com/docs/reel-coach

ポッドキャスト

ポッドキャストのノートは IR JSON を metadata に保存します。コンテンツは IR であり、マークダウンではありません。

作成（クレジット消費なし）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py notes create \
  --type podcast --skip-ai --content '<IR JSON>'

最小 IR 構造：

{
  "speakers": [
    {
      "id": "speaker_1",
      "name": "Eva",
      "role": "host",
      "gender": "female",
      "personality": "Professional, warm"
    }
  ],
  "segments": [
    {
      "id": "seg_ax",
      "speakerId": "speaker_1",
      "script": "[confident] Welcome to the show.",
      "pauseAfterMs": 300
    },
    {
      "id": "seg_bq",
      "speakerId": "speaker_1",
      "script": "Thanks for listening.",
      "pauseAfterMs": 0
    }
  ],
  "globalSettings": {
    "modelId": "eleven_v3",
    "outputFormat": "mp3_44100_128",
    "language": "en"
  }
}

IR のルール：

• speakers[].id：speaker_1、speaker_2 などを使用します。
• segments[].id：seg_ + 小文字のランダムな英字 2 文字（例：seg_ax、seg_bq）。一意である必要があります。
• segments[].speakerId：speakers[].id を参照する必要があります。
• script：音声の演出指示として、任意で [tag] のプレフィックスを付けます — [whispering]、[excited]、[confident]、[pause]、[laughs]。eleven_v3 では、自然な間を表すために ... を使用します。
• pauseAfterMs：必須です。通常は 200–500、話題の切り替え時は 500–800 です。
• audio、audioHistory、audioUnsynced は含めないでください — システムによって管理されます。
• voiceId はスピーカーごとに任意で指定できます。省略した場合は、Studio UI で割り当てるか、既成カタログから指定します。
• 2 人組のポッドキャストでは、"role": "cohost" を指定した 2 人目のスピーカーを追加します。

既成音声カタログ（カスタム ElevenLabs キーは不要）：

女性：Rachel（21m00Tcm4TlvDq8ikWAM）落ち着いた／分析的／温かみのある声、Sarah（EXAVITQu4vr4xnSDxMaL）温かみのある／思慮深い声、Alice（Xb7hH8MSUJpSbSDYk0k2）高揚した／情熱的な声、Matilda（XrExE9yKIg1WjnnlVkGX）温かみのある／内省的な声、Lily（pFZP5JQG7iQjIQuC4Bku）緊張感のある／真剣な声、Emily（LcfcDJNUP1GQjkzn1xUU）落ち着いた／内省的な声。

男性：Brian（nPczCjzI2devNBz1zQrb）落ち着いた／分析的／思慮深い声、Daniel（onwK4e9ZLuTAKqWW03F9）真剣な／思慮深い声、Chris（iP95p4xoKVk53GoZ742B）好奇心旺盛な／遊び心のある／くだけた声、Charlie（IKne3meq5aSn9XLyUdCD）遊び心のある／くだけた声、Bill（pqHfZKP75CvOlQylNhV4）情熱的な／真剣な声、Josh（TxGEqnHWrfWFTfGW9XjX）高揚した／情熱的な声。

TTS を生成（podcast スコープが必要、クレジットを消費）：

mutation {
  generateSegmentAudio(noteId: "...", segmentId: "seg_ax") {
    segmentId audioUrl durationMs
  }
}

AI によるスクリプト編集（1 クレジット）： POST /api/podcast/edit に { "noteId": "...", "prompt": "Make it more conversational" } を指定します。1 つのセグメントに限定するには、"segmentId": "seg_ax" を追加します。応答：{ changes, summary }。自動適用されません — 反映するには updateNote(metadata: updatedIR) を呼び出します。

IR を更新：

mutation {
  updateNote(noteId: "...", metadata: "<stringified IR JSON>") { id updatedAt }
}

updateNote(metadata: ...) を呼び出すたびに、noteMd は IR から自動生成されます。

音声をエクスポート：

mutation {
  exportPodcast(noteId: "...", format: "mp3", paddingMs: 200) {
    url durationMs
  }
}

format："mp3"（デフォルト）では、すべてのセグメントを無音の間を挟んで 1 つのファイルに結合します。"zip" では、間を挟まずセグメントごとに MP3 が 1 つ生成されます。paddingMs（0-10000）を指定すると、各セグメントの後に追加の無音を挿入します（mp3 のみ）。GET /api/audio/<noteId>/export でダウンロードします。速度調整は UI のみで利用でき（API では利用できません）。

ドキュメント全文： https://narrativelion.com/docs/podcast

---

映像制作

プロジェクトの作成

方法	使用する場面	コスト
直接作成（推奨）	エージェントがショットを直接管理する場合	0 クレジット
Film Director	コンセプトがあり、AI 生成のストーリーボードが必要な場合	1-2 クレジット
Reel Coach	ノートから短尺スクリプトを生成する場合	1-2 クレジット

直接作成（0 クレジット）：

# 1. Create empty filmwork note
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py notes create --type filmwork --skip-ai --content '# Project Title'

# 2. Add shots one by one
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-create <noteId> --label 01A --duration 3
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-create <noteId> --label 01B --duration 5
# --after is required once the note has any shot (first shot omits it):
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-create <noteId> --after 01A --duration 2

# 3. Set direction, prompts, etc. via shot-update
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-update <shotUUID> --direction '{"framing":"...","camera":"..."}' --duration 3

Film Director（1-2 クレジット）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py director "concept description" --type animate --duration 30 --aspect 16:9
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py director-persist <threadId> --storyboard <md> --instruction "concept" --type animate --duration 30 --aspect 16:9

Reel Coach（1-2 クレジット）： curl を使用します（CLI ラッパーはありません）。上記の Reel Coach セクションを参照してください。

ラベルは **01A** (Ns) — Title の形式に合わせる必要があります。形式が無効な場合 → INVALID_STORYBOARD_FORMAT。

注意事項

• shot-create --after：最初のショットでは任意ですが、ノートにショットが 1 つでもある場合は必須です（指定しないと afterLabel is required）。
• overview --json：shotId フィールドは UUID ではなくラベルです — UUID は nl.py shot <noteId> <label> で取得します。
• --dialogue は文字列ではなく JSON 配列です：[{"speaker":"...","text":"...","type":"dialogue"|"os"|"sfx_cue","emotion"?:"..."}]。
• --direction のうち、表示に反映されるキー：framing、camera、blocking、keyPose、editTiming、lighting、mood、compositeNote、notes。

エージェントの保留

shot の出力では、アセット／ロールに [HOLD] が付与されます。[HOLD] の場合は、その項目をスキップしてください。

プロジェクトの状態をスキャン

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py overview <noteId>

ステータスの件数とショットごとの概要（アセット、ロール、最高スコア、事前チェック）が表示されます。特定のショットを詳しく確認するには：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot <noteId> <label>

ローカルスタジオに同期する

ゴールデンアセットをローカルスタジオディレクトリにダウンロードします：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py download-shot <noteId> <label> --dir studio/scene/season01/ep01/final/<label>_<scene>/

スタジオディレクトリの規則：studio/scene/season01/ep01/final/{label}_{scene_name}/

ファイル名：{label}_FINAL_start_frame.png、{label}_FINAL_end_frame.png、{label}_SFX_{name}.mp3 など

ショットの作業を始める前に

必ず最初に既存のナレッジを確認します：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decisions <noteId> --shot <shotUUID>
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py insights <noteId>

5秒読むだけで、過去の失敗を繰り返す5分を防げます。

プロンプトを作成または更新する前に

動画プロンプトを作成または変更する前に、サブエージェントを起動し（Agent ツール経由）、関連する知見を確認させます。これにより、生の知見データをメインコンテキストに読み込まずに済みます。

サブエージェントへの指示：

1. nl.py insights --category video --json を実行します（ノートを横断して検索します。1つのプロジェクトに絞る場合は <noteId> を追加します）
2. 画像生成の場合は、代わりに --category image を使用します
3. 返された知見をすべて読みます
4. 現在のショットの内容（カメラの動き、キャラクターの動作、シーンの種類）に関連する知見を、短い箇条書きで返します
5. 関連するプロンプトの知見がなければ、「関連するプロンプトの知見は見つかりませんでした」と返します

トピックがわかっている場合は、--tag を使って結果を絞り込みます（例：--tag motion-direction、--tag start-end-pair）。

制作ループ

Prepare → Preflight → Generate → Review → Act on verdict
                                    ↑               |
                                    └───────────────┘

準備

アセット戦略を変更する場合（開始フレームと終了フレームの入れ替え、フレームの置き換え、再生成、アプローチの変更）は、作業を進める前に必ず strategy_change の判断を記録します。

1. 出典情報を添えて参照アセットをアップロードします：

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> start_frame /path/to/frame.png \
     --method ai_generated --model "gpt-image-2" --prompt "Winter city street..." \
     --parent '{"assetId":"<prev-asset-id>","role":"base"}' \
     --parent '{"externalRef":"claire_fullbody.png — LoRA tier-1","role":"reference"}'
   

2. コレクションの種類（keyframe、sfx、ref_image）には、--label を使用します：

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> sfx /path/to/city_ambience.mp3 --label "City ambience"
   

3. ユーザーがアップロードしたアセット（生成情報なし）には、--method user_upload --user-note を使用します：

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> ref_image /path/to/ref.png \
     --label "Character ref" --method user_upload --user-note "From LoRA training set"
   

アップロード後、「重要な判断（入れ替え、置き換え、新しいアプローチ）を行ったか」を確認します。行った場合は、次に進む前に nl.py decision で記録します。

事前チェック

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py preflight <noteId> <label>

確認項目は3つです：start_frame の準備完了、audio の準備完了、active_prompt の存在。すべて通過するまで生成してはいけません。

生成とアップロード

外部で動画を生成してから、アップロードします：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload-roll <shotUUID> /path/to/video.mp4 --seed 42 --model "kling-2.6" --prompt-version 1

レビューと採点

フレーム抽出の戦略、採点基準、判断マトリクス、レポート形式については、nl-video-score スキルに従います。以下は CLI との連携方法です。

5つの重み付けされた評価項目で採点します（最大55点）：

評価項目	フラグ	重み
顔の一貫性	--face	x3
表情の忠実度	--expr	x3
動き／モーフィング	--motion	x2
安定性	--stability	x2
スタイルの一致度	--style	x1

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py score <rollId> --face 4 --expr 3 --motion 4 --stability 4 --style 4

判定に応じた対応

45点以上 — ゴールデン。確定します：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py verdict <rollId> approved
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py golden-roll <rollId>
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decision <noteId> --shot <shotUUID> --action approve_golden --reason "scored 48, strong across all dimensions" --outcome "locked as golden, moving to next shot"
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-update <shotUUID> --status done

40～44点 — 条件付きで承認します：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py verdict <rollId> approved
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py golden-roll <rollId>
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decision <noteId> --shot <shotUUID> --action approve_with_reservation --reason "scored 42, minor hand drift at 6s" --outcome "approved, may revisit if stronger model becomes available"

30～39点 — 却下して修正します：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py verdict <rollId> rejected
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decision <noteId> --shot <shotUUID> --action plan_revision --reason "face morphing in last 2s" --outcome "adding negative prompt for morphing"

次に、知見を確認し（下記「プロンプトを作成または更新する前に」を参照）、プロンプトを修正して再生成します。何も変更せずに再生成してはいけません。

30点未満 — 却下してデバッグします。再生成してはいけません。 以下のプレイブックに従います。

判断と知見の記録

判断 — 重要な操作を行うたびに記録します：

操作：approve_golden、approve_with_reservation、plan_revision、switch_model、revise_prompt、block_shot、escalate_blocker、analyze_failure、strategy_change。

知見 — 再利用できる知識を見つけたときに記録します：

カテゴリ（モダリティ）：image、video、voice。

タグ（必須、最低1つ）：push-in、pull-out、pan、locked、timelapse、tracking、start-end-pair、single-frame、multi-keyframe、walking、talking、crowd、solo、reaction、insert、motion-direction、style-consistency、lip-sync、compositing、kling、wan、gpt-image、elevenlabs、scoring、review。

例：nl.py insight <noteId> --category video --tags "motion-direction,walking" --title "..." --detail "..."

デバッグプレイブック

スコアが 30 未満のロール

1. 再ロールしないでください。 まず分析します。
2. nl.py roll-context <rollId> — プロンプト、入力アセット、来歴、スコアなど、全体を確認します。
3. nl.py decisions <noteId> --shot <shotUUID> — これまでに試したことを確認します。
4. nl.py insights <noteId> --tag kling（または該当するモデルタグ）— このモデルで知られている問題を確認します。
5. スコアカードを確認します。最も低いスコアの評価項目が修正対象です。
6. nl.py overview <noteId> — 完了したショットはありますか？ 成功したロールのプロンプトと比較します。
7. 記録します：nl.py decision <noteId> --shot <shotUUID> --action analyze_failure --reason "..." --outcome "plan: ..."
8. ここで修正してから再ロールします。

同じショットで 3 回以上ロールが却下された場合

停止してください。再ロールしないでください。

1. nl.py roll-diff <worst-rollId> <best-rollId> — 試行間で何が変わったか（プロンプト、入力、スコア）を正確に確認します。
2. プロンプトのバージョンが異なる場合：nl.py prompt-diff <noteId> <label> --from N --to M — 変更された箇所を正確に確認します。
3. nl.py decisions <noteId> --shot <shotUUID> — これまでに試したことを確認します。
4. nl.py insights <noteId> — このパターンは記録されていますか？
5. 検討します：モデルを切り替える、プロンプトを書き直す、参照フレームを変更する、ショットを簡略化する。
6. 記録します：nl.py insight <noteId> --category video --tags "scoring,review" --title "..." --detail "Shot X required N attempts because..."
7. 記録します：nl.py decision <noteId> --shot <shotUUID> --action strategy_change --reason "..." --outcome "new approach: ..."
8. その後、新しいアプローチを試します。

スコアリングの基準

• 55/55 = 完璧です。非常にまれです。
• 45 以上 = 優秀です。確定します。
• 初回の出力の多くは 35～42 です。正常です。
• ブリーフ自体ではなく、モデルの出力をブリーフに照らして採点します。
• 開始フレームと終了フレームで BG が一致しない場合 = 参照の問題です。フラグを付け、減点しないでください。
• 台本のセリフ中に口がまったく動かない場合 = 想定どおりです（リップシンクは後工程です）。減点しないでください。
• 動かないはずのときに口が動く場合 = モデルの失敗（「活気バイアス」）です。「表情」で減点します。

アセットの来歴

すべてのアセットに、作成方法を記録してください。来歴の記録は常に任意であり、アップロードを妨げることはありません。

アップロード時にインラインで記録する（推奨 — API 呼び出し 1 回）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> end_frame /path/to/end.png \
  --method ai_generated --model "gpt-image-2" \
  --prompt "Based on start_frame, generate end frame of 5s slow push-in..." \
  --parent '{"assetId":"<start-frame-id>","role":"base"}'

後から記録する（来歴が記録されていない既存アセットの場合）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py set-provenance <assetId> \
  --method user_upload --user-note "Downloaded from Midjourney, prompt: ..."

来歴と系譜を照会する：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py roll-context <rollId>         # best starting point — shows prompt, inputs, and provenance in one call
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py provenance <assetId>          # how was this specific asset made?
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py lineage <assetId> --depth 3   # full DAG with parent→child direction
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py prompt <noteId> <label> --version 2  # view a specific prompt version

方法

• ai_generated — AI モデルで作成（モデルとプロンプトを記録）
• user_upload — ユーザーが手動でアップロード（user_note を記録）
• manual_edit — 既存のアセットを手作業で編集
• derived — 機械的に変換（例：セリフからパディングした音声）

親の役割

• base — アセットの派生元となった主要な入力
• reference — 生成の指針となった視覚的な参照
• style — スタイルの参照
• mask — マスクまたはセグメンテーションの入力
• composition — レイアウト／構図の参照
• audio — 音声入力（音声駆動の生成用）

来歴を記録するタイミング

• AI モデルでアセットを生成した場合は必ず記録します。これは最も価値のある系譜データです。
• ユーザーによるアップロードは可能な範囲で記録します。最低限、method: user_upload を記録してください。
• 情報が増えない単純な派生の場合は省略します。
• roll-snapshot はロールのアップロード時に自動で記録されるため、操作は不要です。