officecli-pptx

OfficeCLI PPTX スキル

セットアップ

officecli がない場合:

• macOS / Linux: curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell): irm https://d.officecli.ai/install.ps1 | iex

officecli --version で確認してください（PATH が反映されない場合は新しいターミナルを開いてください）。インストールに失敗した場合は、https://github.com/iOfficeAI/OfficeCLI/releases からバイナリをダウンロードしてください。

⚠️ ヘルプ優先ルール

このスキルは、コマンドのフラグすべてではなく、良いスライドの在り方を説明するものです。プロパティ名、列挙値、エイリアスが不確かな場合は、推測する前にヘルプを参照してください。

officecli help pptx                         # List all pptx elements
officecli help pptx <element>               # Full element schema (e.g. shape, chart, animation, connector, zoom, group)
officecli help pptx <verb> <element>        # Verb-scoped (e.g. add shape, set slide)
officecli help pptx <element> --json        # Machine-readable schema

ヘルプはインストール済みの CLI バージョンを反映しています。スキルとヘルプの記述が食い違う場合は、ヘルプが正です。すぐにヘルプを実行すべき契機: UNSUPPORTED props: の警告、未知のアニメーションプリセット、connector.shape= の列挙値のずれ、プロパティとエイリアスの違い（lineWidth と line.width、color と font.color）。

シェルと実行の規律

シェルのクオート（zsh / bash）。 要素パスは必ず引用符で囲んでください（"/slide[1]/..."）。クオートしない [1] は zsh でグロブ展開され no matches found となります。エスケープは三つの層で行われるため、それぞれ分けて考えてください（二つ目の層は CLI が処理します）。

1. シェル。 値の中の $ はシェルの解釈対象になるため、値全体を単一引用符で囲んでください: --prop text='$15M'。二重引用符の "$15M" は M に展開されてしまいます。CLI は \$ のエスケープを解除してくれません。
2. CLI（text=）。 2 文字のエスケープ \n と \t は pptx / docx / xlsx で一貫して解釈されます。\n は改行（段落の区切り）、\t はタブです。テキストとして円記号に続く n を出力したい場合は \\n と二重にしてください。ただし、これが必要になることはほとんどありません。
3. JSON（バッチ用ヒアドキュメント）。 以下のレシピは cat <<EOF | officecli batch を引用符なしで使い、本文内の $SLIDE / $FILE を展開させています。この引用符なしのヒアドキュメントでは、値内のリテラルの $ も展開されてしまいます。たとえば "$1.42" は黙って .42 になり、"$2.4B" は .4B になります（$1 / $2 は空のシェルパラメータです）。通貨記号は \$ とエスケープしてください。例: "text":"\$1.42"。この形式でも $SLIDE は展開されます。JSON 内の \n / \t はどちらの形式でも機能します。<<'EOF' のように完全に引用符で囲むとすべての $ が保護されますが、その場合は $SLIDE も展開されないため、本文にシェル変数がない場合のみ使用してください。金額を書き込んだ後は view text を実行し、$ が正しく残っているか確認してください。

迷う場合は、書き込み後に view text を実行し、文字単位で比較してください。

段階的な実行。 コマンドを一つ実行したら終了コードを確認してから次に進んでください。コマンド 3 で失敗したスクリプトは、後続の 50 個のコマンドが静かに連鎖的に失敗します。新しいスライド、チャート、アニメーション、コネクタなどの構造的な操作を行った後は、さらに追加する前に get を実行してください。

成果物の要件

ここに挙げるのは、すべてのデッキが満たさなければならない成果物の基準です。いずれか一つでも違反していれば、内容の品質にかかわらず完了とはみなされません。

全デッキ共通

1スライドに1つのアイデア。 スライドの内容を説明するのに2つ目のタイトルが必要なら、分割してください。「Xに関するすべて」を詰め込んだ高密度のスライドは、聴衆が3秒で内容を見失います。関連する1アイデアのスライドをまとめるにはセクション区切りを使い、巨大なスライドを作らないでください。

型の階層を明示的に指定し、テーマのデフォルトに頼らないでください。 テーマのデフォルトはマスターごとに異なる場合があります。すべてのテキストシェイプにサイズを明示的に設定してください。

要素	最小	一般的	最小シェイプ高さ
スライドタイトル	≥ 36pt 太字	36〜44pt	≥ 2cm
セクション / サブタイトル	≥ 20pt	20〜24pt	≥ 1.2cm
本文	≥ 18pt	18〜22pt	≥ 1cm
キャプション / 軸ラベル	≥ 10pt 控えめな色	10〜12pt	≥ 0.6cm

目安として 最小シェイプ高さ ≈ フォントサイズ(pt) × 0.05cm です。高さ0.8cmのボックスに入れた18ptのサブラベルは溢れます。view annotated でこの問題を検出できます。

タイトルは 本文サイズの2倍以上にしてください(20ptの本文に対して36ptは適切ですが、28ptでは控えめすぎて見えます)。本文18pt以上の原則には4つの正当な例外があります:グラフの軸ラベル、凡例、フッター / ページ番号、および5語以内のKPIサブラベル(例:「Active users」)。説明文は必ず18pt以上にしてください。本文は左揃えにし、中央揃えはタイトルと主要な数値のみに使用してください。「カードが収まらない」場合は、フォントを縮小するのではなくカードを減らしてください。

フォントは最大2種類、パレットは1つ。 見出し用フォント1つと本文用フォント1つ(例:Georgia + Calibri)を使用してください。大きな数字やカバータイトルに限り、3つ目のディスプレイ用書体を使ってもかまいませんが、その見出しと本文の組み合わせは維持してください。ブランドカラー1色を全体の60〜70%の比率で主役にし、補助色1色とアクセント色1色を加えてください。本文コンテンツで4色以上を混在させないでください。デザイン原則に記載されたパレットとフォントの組み合わせは、最低基準であり、選択肢の一覧ではありません。 ユーザーがブランドカラーやフォント、既存のテンプレートを指定している場合は、まずそれに合わせてください。指定がなければ、名前付きのセットは調整済みの出発点です。それらを自由に組み合わせたり、変えたりしてかまいませんが、結果がそれより劣るものになってはならず、コントラストの最低基準は満たしてください。

すべてのスライドに、情報を伝える非テキストのビジュアルを載せてください。 装飾ではなく、意味を伝える図形、グラフ、アイコン、グラデーションの帯などを使用してください。箇条書きだけのデッキは、Wordの文書と変わりません。例外は、引用文だけのスライド、コードブロック、単独の要約表スライドです。

少ないほど良い。すべての要素には存在理由が必要です。 上記のビジュアルのルールは箇条書きの壁を防ぐためのものであり、雑然とさせてよいという許可ではありません。情報を伝えない装飾的な数値、アイコン、埋め草のセクションで水増ししないでください(「データのスロップ」)。スライドが寂しく見える場合は、内容を捏造するのではなく、レイアウトと余白で対処してください。内容を膨らませるのではなく範囲を絞り、大きな追加が必要な場合は、勝手に行わず指摘してください。

すべての本編スライドにスピーカーノートを付けてください。 --type notes --prop text="..." を使用します。発表者には原稿が必要ですが、聴衆がスライドをそのまま読むべきではありません。

文章は人間らしく、AIらしくないものにしてください。 タイトルは決め台詞ではなく、内容に基づいて付けてください。「それはXではない。Yだ。」という言い回し、作為的な緊張感、もっともらしい洞察風の表現(「魔法の瞬間」)、一語のドラマチックな表現(「勢い。」)は使わないでください。誇張的な形容詞(シームレス、堅牢、ゲームチェンジャー)は削除し、数字に語らせてください。

既存のテンプレートを維持してください。 ファイルにすでにテーマとマスターがある場合は、それに合わせてください。既存の慣習は、これらのガイドラインより優先されます。

視覚的な納品基準（すべてのスライドデッキに適用）

完了を宣言する前に、スライドごとのレンダリング結果（QA を参照）が以下を満たしている必要があります。

• プレースホルダートークンがコンテンツとして表示されていないこと。 {{name}}、$fy$24、<TODO>、lorem、xxxx、グラフタイトル内の空の ()/[] が表示されてはいけません。
• 端からのはみ出しや、図形内のテキストの切れがないこと。 view issues は両方（shape_off_slide とテキストフィットのヒント）を検出します。切れを直すには、ボックスを広げるか値を短くしてください。コンテンツを削ってスペースに収めてはいけません。
• 表紙に案内要素があること。 タイトル、サブタイトル、発表者／クライアント、日付、ブランド帯またはキーメッセージのストラップを含めてください。タイトルだけの表紙は中身のないスタブに見えます。周囲に十分な余白を取ることは引き続き正しいですが、情報量が多いことと詰め込みすぎは別物です。
• コントラスト。 view issues は一般的なケース、つまり図形自身の濃い塗りの上にある不透明な濃色テキスト（low_contrast）は自動で検出します。しかし、アイコンやグラフ系列の塗り、スキーム色や継承色、独立した背景図形の上にあるテキストは検出できません。そのため、明度が 30% 未満の塗り（1E2761、36454F、深い森林色／ベリー色／チェリー色）の上では、すべての本文のラン、カード本文、グラフ系列、アイコンが FFFFFF か明度 80% 超であることを必ず確認してください。中間グレー（6B7B8D は約 44%）はノートパソコンの画面では読めても、プロジェクターでは見えなくなります。暗い塗りの確認を行った後、view html で抜き取り確認してください。

いずれかが満たされない場合は、作業を止めて修正してから完了を宣言してください。

デザインの原則

スライドデッキは文書ではありません。聴衆が各スライドを理解するのに使える時間は 3 秒です。何かを追加する前に、「聴衆が最も大きい要素だけを見て一度ざっと目を通したとき、要点が伝わるか」と自問してください。箇条書きを読まなければ要点が分からないのであれば、最も大きい要素が間違っています。

グリッド、余白、ネガティブスペース

標準のワイドスクリーンは 33.87 × 19.05cm です。内部では 12 列のグリッドとして扱ってください。

• 端の余白は 1.27cm（0.5"）以上を四辺すべてに取ってください。
• ブロック間の間隔は 0.76cm（0.3"）以上をカード／列／行の間に取ってください。値は一つ（0.76cm または 1.27cm）に決めて、全体で統一してください。間隔がばらばらだと未完成に見えます。
• スライドごとに 20% 以上のネガティブスペースを確保してください。画面のすべてのピクセルを埋めると、素人っぽく見えます。
• Web 的に中央寄せするのではなく、構成してください。 余白は構造の一部です。下三分の一が空いていて上寄りに配置されたスライドは、正しい構成であり、空の欠陥ではありません。意図的な非対称性（左にコンテンツ、右に余白）は、すべてを中央に揃えるよりもデザインされた印象を与えます。そこに隙間があるというだけの理由で埋めないでください。
• カードのグリッドでは、usable = 33.87 − 2·margin − (N−1)·gap を計算し、col_width = usable / N とします。x 座標を手で決めないでください。

フォントの組み合わせ

新奇さではなく、文書のレジスターで組み合わせを選んでください。「Best For」は指針であり、決定事項ではありません。この表以外の組み合わせも、目的に合えば問題ありません。ここに挙げた 8 つは出発点であり、全体ではありません。

見出し	本文	最適な用途
Georgia	Calibri	正式なビジネス、財務、経営層向けレポート
Arial Black	Arial	力強いマーケティング、製品ローンチ
Calibri	Calibri Light	すっきりしたコーポレート、ミニマルなデザイン
Cambria	Calibri	伝統的なプロフェッショナル、法務、学術
Trebuchet MS	Calibri	親しみやすいテック、スタートアップ、SaaS
Impact	Arial	力強い見出し、イベントのデッキ、基調講演
Palatino	Garamond	洗練されたエディトリアル、ラグジュアリー、非営利
Consolas	Calibri	開発者ツール、技術／エンジニアリング

タイトルには --prop font=Georgia、本文には --prop font=Calibri を用いて、すべての図形で両方のフォントを明示的に設定してください。テーマからの継承には頼らないでください。

配色とコントラスト

列の意味: Primary（主色 — 重みの60〜70%を占め、最初に目に入る色）、Secondary（補助的な色調）、Accent（控えめに、一箇所だけ強調するための色）、Text（明るい背景上の本文）、Muted（キャプション・軸ラベル・フッター）。

Theme	Primary	Secondary	Accent	Text	Muted
Coral Energy	F96167	F9E795	2F3C7E	333333	8B7E6A
Midnight Executive	1E2761	CADCFC	FFFFFF	333333	8899BB
Forest & Moss	2C5F2D	97BC62	F5F5F5	2D2D2D	6B8E6B
Charcoal Minimal	36454F	F2F2F2	212121	333333	7A8A94
Warm Terracotta	B85042	E7E8D1	A7BEAE	3D2B2B	8C7B75
Berry & Cream	6D2E46	A26769	ECE2D0	3D2233	8C6B7A
Ocean Gradient	065A82	1C7293	21295C	2B3A4E	6B8FAA
Teal Trust	028090	00A896	02C39A	2D3B3B	5E8C8C
Sage Calm	84B59F	69A297	50808E	2D3D35	7A9488
Cherry Bold	990011	FCF6F5	2F3C7E	333333	8B6B6B

デフォルトではなく、トピックに応じて選んでください。金融なら Midnight Executive、製品ローンチなら Coral Energy、安全・LOTO（ロックアウト・タグアウト）なら Cherry Bold が適しています。最も近い名前付きテーマが完全には合わない場合は、組み合わせてください（例：Forest の主色に金色 D4A843 のアクセント）。明るい背景には Text を、キャプション・軸・フッターには Muted を使い、暗い背景上の本文には FFFFFF または Secondary を使います。

暗い背景では、テキストとチャート系列は上記のハードルールにあるコントラストの下限に従います。

グラフ種類の選択表

グラフの種類を誤ると3秒テストで失敗します。

データの形	使用	避ける
カテゴリ比較（A vs B vs C）	column（縦）/ bar（6カテゴリ以上なら横）	pie（扇形が混ざる）、line（時間軸がない）
時系列、1〜3系列	line	area（重なりで見えにくい）、bar（離散的だと誤解させる）
全体に対する部分、2〜5スライス	pie / doughnut	8スライス以上の pie（読み取り不能）
相関 / 分布	scatter	line（順序があると誤解させる）
複数カテゴリ × 指標、高密度	積み上げ column またはヒートマップ	指標ごとに1グラフ — 統合する
KPI の概要（単一の大きな数値）	大きな文字のシェイプ（60〜72pt + 5語以内のサブラベル）。グラフではない	ゲージグラフ、小さな bar

経験則：系列が3を超え、かつカテゴリが8を超える場合は、2つのグラフに分割するか、表に切り替えてください。

アニメーション

ブランドとコンテンツが求める分だけ、多くも少なくも使ってください。格式ある金融系のデッキではほぼゼロに抑える傾向があり、製品ローンチではより表現力を持たせても構いません。アニメーションは装飾ではなくツールです。デッキを損なわないために、次の3つの基準を守ってください（使用量の上限を定めるものではありません）。

• 目的がある — 各アニメーションは内容を見せる、または強調するためのものであり、装飾のためのものではありません。理解の助けにならないなら削除してください。
• 段階的に劣化する — pptx のアニメーションは閲覧環境（Keynote / Slides / Web / モバイル）によって表示が一定せず、まったく再生されないこともあります。そのため、すべてのスライドは 静止画 の状態でも正しく読める必要があります。重要なコンテンツをアニメーションの裏に隠さないでください。
• 実際に確認する — アニメーションは実行時にのみ動作するため、view html やスクリーンショットでは確認できません。公開前に必ず実際のプレゼンテーション閲覧ツールで確認してください。

指針（禁止ではありません）：fade / appear / 単一の zoom-entrance を、数百ミリ秒程度の素早い時間で使うのがほとんどのデッキに適しています。bounce / swivel / spin / fly-from-edge や、多数のオブジェクトを複雑に動かす演出は、たいてい素人っぽく見えます。ブランドが意図的に遊び心を求めている場合にのみ使ってください。

レイアウトのパターンとデータ表示

スライド間でレイアウトを変えてください。同じパターンを繰り返すと、すべてのスライドが同じに見えてしまいます。以下は一般的な構成要素であり、全種類を網羅したものではありません。スライドごとに一つ選ぶか、内容に応じて表の外にレイアウトを組んでください。

パターン	使用する場面	主な寸法
2カラム（左にテキスト、右にビジュアル）	コンセプトと根拠、機能とスクリーンショット	各カラム約14〜15cm、間隔1cm
アイコン行（塗りつぶしの円内のアイコン＋太字の見出し＋説明文）	機能一覧、メリット、チームの役割	アイコンの円1.5〜2cm、最大3〜4行
2×2または2×3のグリッド（カードタイル）	象限分析、SWOT、選択肢の比較	間隔0.76cm以上、カードの高さを揃える
ハーフブリード画像（左または右の半分を画像にし、反対側に内容を重ねる）	ヒーローの場面、事例紹介の冒頭	画像の幅16〜17cm、内容カラムは14cm以上
大きな数値の強調（60〜72ptの数字＋その下に5語以内の補足ラベル）	単一のKPI、マイルストーン、市場規模	グラフではなく図形を使う。補足ラベルは14〜16ptの控えめな色

データ表示のクイックルール:

• 2〜3の選択肢の比較（前後の比較、AとBの比較）には、表よりも比較用のカラムの方が適しています。
• タイムラインやプロセスフローには、箇条書きではなく、番号付きのステップ図形とコネクタを使ってください。

画像の扱い（スライドで写真・スクリーンショット・ロゴを使う場合のみ）

まず画像を開いて確認し、ファイル名だけで配置せず、見た内容に基づいて扱い方を選んでください。

• 全面の写真 → 領域をカバーするようにサイズを調整（端をトリミング）し、枠線は付けない。
• スクリーンショット・図表・ロゴ → 領域に収まるようにサイズを調整（内容は決して切り取らない）。透明な画像や収まった画像は、コントラストのある塗りの上に置いてください。白背景に浮かせず、背後に有色の長方形を配置してください。
• 写真の上のテキスト → 画像の上に直接置かないでください。カードに載せるか、画像とテキストの間に保護用のスクリム（濃い長方形を不透明度50〜60%程度にする、またはテキスト側の端からグラデーションでフェードさせる）を敷いてください。
• 縦横比を歪めて引き伸ばさないでください。また、雑然としたスクリーンショットの上にテキストを重ねないでください。
• ユーザーが提供した画像やブランド素材を優先してください。依頼がない限り、絵文字や自作のイラストは使わないでください。

ビジュアルのモチーフの一貫性

特徴的な要素を一つ選び（角丸の画像枠、塗りつぶし円の中のセクション番号、片側だけの境界帯、斜めのアクセントストリップなど）、すべてのスライドで一貫して使ってください。デッキ全体で統一してください。一つのスライドだけに装飾を施し、残りを無地のままにすると、制作が途中で放棄されたように見えます。副次的なモチーフは、主要なモチーフと競合しない場合に限り使用できます。最初に制作計画の中で宣言してください。例: ## Motif: numbered circles in brand color

避けるべきビジュアル上のAIらしさ

• スライドのタイトル下に装飾的な下線を引かないでください。 見出しの下の帯や罫線は、AIが作ったスライドに最もよく見られる特徴です。余白や背景色の変更を使ってください。
• 角丸のカードに、色付きの左側の境界線アクセントを付けないでください。 これもAIスライドに典型的な特徴です。代わりに、単色の塗り、上部のアクセント帯、または余白による区切りを使ってください。
• ブランドが使っていない限り、絵文字をアイコンとして使わないでください。 図形や実際のアイコン素材を使ってください。

コピーレベルの特徴については「Copy reads human」に記載されています。

一般的なワークフロー

1. 開く／保存のライフサイクル。 作業の開始時に officecli open <file>、終了時に officecli save <file> を実行して編集内容をディスクに書き出します。save は書き込みのみを行い、後続の編集に備えて常駐プロセスをウォーム状態のまま残します。officecli close <file> は、常駐プロセスを即座に解放したい場合（一回限りの引き渡し）にのみ使用してください。どちらも常に安全で、エラーになったり作業内容を失ったりすることはありません。反復的な図形のグリッドには batch を使用してください。フラッシュは officecli 外のプログラムとの境界でのみ行ってください。 officecli 自身による読み取りでは、常に編集内容が反映されます。officecli 以外のプログラム（python-pptx、PowerPoint、レンダラー、納品作業）がファイルを読み込む前にのみ save／close を実行してください。
2. 全体把握。 新規のプレゼンテーションの場合は officecli create "$FILE" を実行します。既存のものの場合は、まず officecli view "$FILE" outline を実行します。盲目的に編集しないでください。
3. タイトルの流れを最初に計画します（まだ構築しないでください）。 スライドや図形を作成する前に、スライドタイトルを順番どおりに書き出した一覧を作成します。タイトルだけを読んだ人が議論の流れを追えない場合は、今この段階で構成を修正してください。一覧で直すほうが、14枚のスライドを作ってから直すよりはるかに低コストです。タイトルの書き方は一つに決めてください。すべて名詞句のトピックにするか、すべて行動を示す文にするかのどちらかで、混在させず、全体を通して統一してください（「コピーは人が読みやすいか」を参照）。
4. 表示順に構築します。 聴衆が見る順序でスライドを追加してください。表紙 → アジェンダ → セクション1の区切り → セクション1の内容 → セクション2の区切り → … → 締めくくり、の順です。スライド追加の --index も使えますが、末尾への順次追加のほうが構築スクリプトが読みやすく、インデックス計算のミスも避けられます。最終納品の前に、スライド枚数と物語の流れが構築計画と一致しているか確認してください。 ゲート3の順序チェックで、表紙が14枚中の11枚目になっているような問題を検出できます。
5. スライドごとに段階的に作成します。 スライドと背景を作成し、次にタイトル、続いて補助的な図形・グラフ・コネクタを追加します。カスタムデザインでは常に layout=blank を使用してください。構造的な操作を行うたびに get /slide[N] --depth 1 を実行して図形IDを確認してください。
6. 仕様どおりに書式を整えます。 要件表に従ってください。書式設定は仕上げの装飾ではなく、成果物の一部です。
7. 保存と検証。 officecli save でファイルをディスクに書き出します（セッションも終了する場合は officecli close を使用します）。出荷前には必ず対象のプレゼンテーションビューアーで開いてください。グラフの色、アニメーション、フォント、ズームはランタイム機能であり、view html では再現できません。詳しい検証は下記のQAで行います。
8. QA — 問題があるものと想定してください。 修正と検証を、サイクルで新たな問題が一つも見つからなくなるまで繰り返します。

クイックスタート

最小構成のプレゼンテーションです。表紙、コンテンツスライド1枚、ノートで構成します。$FILE はファイル名の代わりです。

FILE="deck.pptx"
officecli create "$FILE"
officecli open "$FILE"

# Cover — dark fill, centered title
officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761
officecli add "$FILE" /slide[1] --type shape --prop text="FY26 Strategic Review" \
  --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=3cm \
  --prop font=Georgia --prop size=44 --prop bold=true --prop color=FFFFFF --prop align=center

# Content — white fill, title + body + notes
officecli add "$FILE" / --type slide --prop layout=blank --prop background=FFFFFF
officecli add "$FILE" /slide[2] --type shape --prop text="Revenue grew 18% YoY" \
  --prop x=1.5cm --prop y=1.2cm --prop width=30cm --prop height=2cm \
  --prop font=Georgia --prop size=36 --prop bold=true --prop color=1E2761
officecli add "$FILE" /slide[2] --type shape --prop text="Enterprise renewals + new EMEA region drove the beat; NRR held at 118%." \
  --prop x=1.5cm --prop y=4cm --prop width=30cm --prop height=3cm \
  --prop font=Calibri --prop size=20 --prop color=333333
officecli add "$FILE" /slide[2] --type notes --prop text="Lead with the 18% beat, preview EMEA."

officecli save "$FILE"
officecli validate "$FILE"

どの構築も同じ流れです。開く → スライドと背景 → タイトル → 本文 → ノート → 保存 → 検証。

読み取りと分析

広く把握してから絞り込みます。まず outline を実行し、確認対象の場所が分かったら view text／get／query を使用してください。

officecli view "$FILE" outline          # slide count + titles
officecli view "$FILE" annotated        # complete per-slide breakdown with fonts, sizes, tables, charts
officecli view "$FILE" text --start 1 --end 5   # text dump (includes table cell text)
officecli view "$FILE" issues           # empty slides, overflow hints
officecli view "$FILE" stats            # counts + totals (incl. pictures missing alt)

要素を個別に確認する。 XPath形式のパスで、1始まりです。必ず引用符で囲んでください。位置指定の [N] よりも @name=／@id= セレクターを優先してください（並べ替えに対して安定します）。[last()] も使用できます。機械処理用の出力には --json を付けてください。

officecli get "$FILE" "/slide[1]" --depth 1              # shape list with IDs and names
officecli get "$FILE" "/slide[1]/shape[@name=Title]"
officecli get "$FILE" "/slide[1]/table[1]" --depth 3     # table rows / cells

プレゼンテーション全体を検索する。 CSS風のセレクターを使用します。演算子は =、!=、~=、>=、<=、[attr]、:contains()、:no-alt です。help pptx query で検索可能な要素の種類を一覧できます。

officecli query "$FILE" 'shape:contains("Revenue")'
officecli query "$FILE" 'picture:no-alt'                 # accessibility gap
officecli query "$FILE" 'shape[fill=1E2761]'             # color match
officecli query "$FILE" 'shape[width>=10cm]'             # numeric

query --json の出力スキーマ。 結果は .data.results[] で包まれています。例：jq -r '.data.results[0].format.id'。.[0].id ではありません。図形名は .name、塗りつぶしは .format.fill、文字色は .format.textColor です。

視覚的プレビュー（最優先）。

officecli view "$FILE" html                # prints an HTML preview path; Read it for per-slide visual audit (best structural ground truth)
officecli view "$FILE" svg --start 3 --end 3   # single slide SVG (charts + gradients do NOT render in SVG)

出力の読み方：想定される非欠陥。

• layout=blank にはタイトルプレースホルダーがありません。 タイトルは通常の shape 要素として配置されるため、view outline が (untitled) と表示するのは想定どおりで、欠陥ではありません。スクリーンリーダーでのアウトライン互換性が重要な場合にのみ、layout=title と placeholder[title] を使用してください。

作成と編集

操作動詞は add／set／remove／move／swap／batch／raw-set です。プレゼンテーションの9割は、スライド、図形、テキスト、いくつかのグラフ、画像、コネクタで構成されます。

スライドと背景

スライドは /slide[N] で指定します。カスタムデザインでは常に layout=blank を指定してください。背景には、単色、グラデーション、画像を使用できます。

officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761                 # solid
officecli add "$FILE" / --type slide --prop layout=blank --prop "background=1E2761-CADCFC-180"   # gradient (start-end-angle)
officecli add "$FILE" / --type slide --prop layout=blank --prop background=image:/path/to/hero.jpg  # image background (LEAD)

Shapes

shape は、テキスト、塗りつぶし、枠線、位置、および任意のアニメーションやリンクを保持します。

officecli add "$FILE" /slide[2] --type shape --prop name=Title --prop text="Key Insight" \
  --prop x=2cm --prop y=2cm --prop width=20cm --prop height=3cm \
  --prop font=Georgia --prop size=36 --prop bold=true --prop color=1E2761 --prop fill=none

配置は明示的に指定します。レイアウトエンジンはなく、グリッドの計算は自分で行います。--prop preset= で形状を選択します（rect、roundRect、ellipse、triangle、arrow、star5 など）。カスタムの M...Z パスはサポートされていないため、プリセットを選んでください。図形は作成時に名前を付けてください（--prop name=HeroTitle）。その後は "/slide[N]/shape[@name=HeroTitle]" で参照できます。名前は z 順の変更や削除後の再追加でも維持されますが、位置指定の /shape[3]（および @id= でも）はずれてしまいます。構造を変更した後は、位置インデックスを使う前に get --depth 1 を再実行してください。

図形内のテキスト（段落、ラン、スタイル）

図形には段落（paragraph[K]）とラン（run[K]）があります。一行のテキストであれば、図形の --prop text= で十分です。テキスト内の \n は段落の区切り、\t はタブになります（シェルと実行の注意事項を参照してください。リテラルの \n には \\n と二重にします）。add --type paragraph は図形と同じスタイルのプロパティ（text、align、bold、italic、size、color、font）を受け付けます。一行の中で混在したスタイルを適用する場合は、スタイル付きのランを追加します。

officecli add "$FILE" "/slide[2]/shape[@name=Card1]/paragraph[1]" --type run \
  --prop text=" (inline detail)" --prop size=14 --prop italic=true --prop color=8899BB

チャート

チャートの種類は、デザイン原則のチャート選択表に従って選んでください。プロパティの全一覧（chartType の列挙値、seriesN.*、data=/categories=、軸のオプション）は help pptx add chart を参照してください。ブランドカラーを使った典型的な複数系列の例は次のとおりです。

officecli add "$FILE" /slide[3] --type chart --prop chartType=column \
  --prop series1.name=Revenue --prop series1.values="42,45,48" --prop series1.color=1E2761 \
  --prop series2.name=Growth  --prop series2.values="2,7,7"    --prop series2.color=CADCFC \
  --prop categories="Q1,Q2,Q3" \
  --prop x=2cm --prop y=4cm --prop width=20cm --prop height=10cm

注意点：(1) ()、[]、TBD を含むチャートのタイトルは、そのままの文字列として表示されます。(2) 一部のビューアーはチャートの色をテーマの既定値に置き換えます。対象のビューアーで必ず確認してください。系列は作成後にも追加できます（add --type series）。

画像

officecli add "$FILE" /slide[4] --type picture --prop src=hero.jpg \
  --prop x=1cm --prop y=1cm --prop width=32cm --prop height=18cm \
  --prop alt="Product hero, gradient lit from right"

officecli query "$FILE" 'picture:no-alt' で確認してください。納品前に結果が空である必要があります。

コネクタ（重点：フローチャートと決定木）

2 つの図形間、または任意の座標の間に線を引きます。プロパティと列挙値の完全なリファレンス（shape、headEnd/tailEnd の値、from/to の参照形式）は help pptx add connector を参照してください。

officecli add "$FILE" /slide[5] --type connector \
  --prop "from=/slide[5]/shape[@name=BoxA]" --prop "to=/slide[5]/shape[@name=BoxB]" \
  --prop shape=elbow --prop color=333333 --prop tailEnd=triangle

フローのコネクタにはすべて矢印の先端が必要です。 矢印がないと、bentConnector3 は方向のない線として描画されます。preset=rightArrow の重ね表示は水平方向のフローにしか使えません。分岐する辺を持つひし形や決定木では tailEnd= を使ってください。

アニメーション（重点）

上記のアニメーションの基準に従って使用してください（目的を持って使い、適切に劣化し、実際に表示して確認すること）。プリセット名と時間の構文は help pptx animation を参照してください。

officecli set "$FILE" "/slide[2]/shape[@name=HeroCard]" --prop animation=fade-entrance-400
officecli set "$FILE" "/slide[2]/shape[@name=HeroCard]" --prop animation=none    # clear all

ハイパーリンク、ツールヒント、スライドへのジャンプ

--prop link=slide[N] は、同じプレゼンテーション内のスライドへのジャンプになります（1 始まり。対象のスライドが存在している必要があります）。link=nextslide / firstslide / lastslide / previousslide / endshow は名前付きのナビゲーションに使います。link=https://... は URL へのリンクです。--prop tooltip="..." はホバー時に表示されるテキストです。

表、プレースホルダー、グループ、ズーム：簡単な例

• 表：--type table --prop rows=N --prop cols=M。行単位の set は height と c1/c2/c3（セルの初期テキスト）をサポートします。ヘッダー行のスタイルは表全体の設定（firstRow=true / headerFill=）で指定し、行のプロパティではありません。セルの書式はセルの段落またはランに設定します。行を埋めた後に表全体のフォントを設定してください（行の操作でフォントの継承がリセットされるためです）。
• プレースホルダー："/slide[N]/placeholder[title]" / placeholder[body]。プレースホルダーを持つレイアウトを使用しているスライドでのみ利用できます（layout=blank では使えません）。
• グループ（重点）：子要素は "/slide[N]/group[@name=G]/shape[1]" で参照します。位置インデックスより、並べ替えに強い参照方法です。
• ズームスライド（重点）：--type zoom --prop target=N（リンクは対象ごとに 1 つ。別名は slide）。複数のターゲットを持つナビゲーションハブでは、ズームの図形を N 個別々に追加します。ズームは実行時の機能です。view html では静的な配置のみが表示され、ズームの操作はライブのプレゼンテーションビューアーでのみ動作します。
• スライドのコメント：レビュー用の注釈で、/slide[N]/comment[M] に紐付けられます。ライフサイクル全体（add / set / get / query / remove）に対応しています。プロパティは text、author、initials（自動生成）、date（ISO 8601 形式、既定値は UtcNow）、x / y（長さの基準点）です。

  officecli add "$FILE" "/slide[2]" --type comment --prop author="Alice" --prop text="Tighten this bullet" --prop x=20cm --prop y=3cm
  officecli query "$FILE" 'comment' --json | jq '.data.results | length'   # count all review comments
  officecli remove "$FILE" "/slide[2]/comment[1]"                           # resolve after addressing
  

デッキレベルのレシピ

基本要素だけでは分かりにくいパターンです。各レシピでは最初に視覚的な結果を示し、その後に実行可能なブロックを載せています。$FILE はお使いのファイル名です。直前に追加したスライドを指定するには /slide[last()] を使用してください。これらのレシピは構造と座標計算を示すものです。トピックに合わせて選んだパレットやフォントに置き換えてください。ネイビーの 1E2761 と Georgia は例のテーマにすぎず、そのままコピーすべきスタイルではありません。

Z 順序。 後から追加した図形ほど前面に表示されます。背景の装飾を先に追加し、タイトルは最後に追加してください。後から修正する場合は --prop zorder=back/front を使用します（同階層の要素の番号が振り直されるため、さらに重ねる前に get --depth 1 で再取得してください）。

(a) 表紙（およびセクション区切り）

視覚的な結果。 ダークネイビーの塗りつぶし、中央揃えの 44pt タイトル、18pt のアイスブルーのメタ行。

officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761
officecli add "$FILE" "/slide[last()]" --type shape --prop text="Strategic Growth Review" \
  --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=3cm \
  --prop font=Georgia --prop size=44 --prop bold=true --prop color=FFFFFF --prop align=center
officecli add "$FILE" "/slide[last()]" --type shape --prop text="Prepared for Acme Leadership — FY26 Outlook" \
  --prop x=2cm --prop y=11cm --prop width=29.87cm --prop height=1.2cm \
  --prop font=Calibri --prop size=18 --prop color=CADCFC --prop align=center

セクション区切り は、表紙と同じ構成に、巨大な半透明の数字（size=120、opacity=0.15）を最初に追加したものです。これによりセクションタイトルの背後に配置されます。

(b) データスライド（グラフ＋解説ブロック）

視覚的な結果。 左側の3分の2に、ブランドのシリーズカラーを使った縦棒グラフ。右側の3分の1に、20pt の見出しと 18pt の本文からなる「Key Insight」カード。読み手は棒グラフを読み取る前に要点を把握できます。

officecli add "$FILE" / --type slide --prop layout=blank --prop background=FFFFFF
officecli add "$FILE" "/slide[last()]" --type shape --prop text="FY26 Revenue Beat Plan by 18%" \
  --prop x=1.5cm --prop y=1cm --prop width=30cm --prop height=1.8cm \
  --prop font=Georgia --prop size=36 --prop bold=true --prop color=1E2761

# Chart — left 2/3 (single-quote the title because of `$`)
officecli add "$FILE" "/slide[last()]" --type chart --prop chartType=column \
  --prop series1.name=Actual --prop series1.values="42,45,48,55" --prop series1.color=1E2761 \
  --prop series2.name=Plan --prop series2.values="40,42,45,48" --prop series2.color=CADCFC \
  --prop categories="Q1,Q2,Q3,Q4" --prop x=1.5cm --prop y=3.5cm --prop width=20cm --prop height=14cm --prop title='FY26 Revenue ($M)'

# Commentary card — right 1/3: background + heading + body
officecli add "$FILE" "/slide[last()]" --type shape --prop preset=roundRect --prop fill=F5F7FA --prop line=none \
  --prop x=22.5cm --prop y=3.5cm --prop width=9.8cm --prop height=14cm
officecli add "$FILE" "/slide[last()]" --type shape --prop text="Key Insight" \
  --prop x=23cm --prop y=4cm --prop width=9cm --prop height=1.2cm \
  --prop font=Georgia --prop size=20 --prop bold=true --prop color=1E2761
officecli add "$FILE" "/slide[last()]" --type shape --prop text="EMEA launch + NRR at 118% drove 12pp of the 18pp beat." \
  --prop x=23cm --prop y=5.5cm --prop width=9cm --prop height=11cm \
  --prop font=Calibri --prop size=18 --prop color=333333

(c) フローチャート／プロセス図（ボックスとコネクタ）

視覚的な結果。 y=8cm の位置に、各 6×3cm の角丸ボックスを 4 つ横に並べます。ネイビーとアイスブルーを交互に使い、三角形の矢じりを付けた肘継ぎコネクタで結びます。

グリッドの計算（ボックス 4 つ、スライド幅 33.87cm、左右の余白 1.5cm）: gap = (33.87 − 3 − 24) / 3 = 2.29cm。x 座標は 1.5, 9.79, 18.08, 26.37 です。

各ボックスのラベルは valign=middle で直接設定します（別途オーバーレイ用の図形は不要です）。移植性のある座標計算には batch のヒアドキュメントを使用してください。bc や bash の配列は使用しません。

cat <<EOF | officecli batch "$FILE"
[
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step1","preset":"roundRect","fill":"1E2761","line":"none","x":"1.5cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 1","font":"Georgia","size":"20","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step2","preset":"roundRect","fill":"CADCFC","line":"none","x":"9.79cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 2","font":"Georgia","size":"20","bold":"true","color":"1E2761","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step3","preset":"roundRect","fill":"1E2761","line":"none","x":"18.08cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 3","font":"Georgia","size":"20","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Step4","preset":"roundRect","fill":"CADCFC","line":"none","x":"26.37cm","y":"8cm","width":"6cm","height":"3cm","text":"Step 4","font":"Georgia","size":"20","bold":"true","color":"1E2761","align":"center","valign":"middle"}}
]
EOF

# Connector pattern — reuse for any box-to-box graph.
for pair in "Step1 Step2" "Step2 Step3" "Step3 Step4"; do
  A=${pair% *}; B=${pair#* }
  officecli add "$FILE" "/slide[$SLIDE]" --type connector \
    --prop "from=/slide[$SLIDE]/shape[@name=$A]" \
    --prop "to=/slide[$SLIDE]/shape[@name=$B]" \
    --prop shape=elbow --prop color=333333 --prop tailEnd=triangle
done

shape=elbow が標準です（bentConnector2 / bentConnector3 も使用できます）。

(d) 複数スライドからなるデッキの骨格

コードブロックはありません。これはリズムの例です。以下の並びは一つの運用パターン（暗い区切りスライドと白い内容スライドの交互配置）の例であり、必須の順序ではありません。まずコンテンツから実際の流れを導き出し（「タイトルの並びを先に決める」を参照）、そのうえで区切りと内容のリズムを適切なものから選んでください。

• 10 スライドのレビュー: 表紙 · アジェンダ · KPI 3 点 · 区切り01 · グラフ · グラフ · 区切り02 · フロー · タイムライン · クローズ
• 20 スライドのピッチ: 同じリズムを 2 倍にし、課題 · ソリューション · 市場 · プロダクト · トラクション · モデル · チーム · 財務 · 依頼事項 のセクションに分けます
• すべての区切りは、それに続くセクションの内容より前に配置してください（ゲート 3 の順序確認）
• 表紙／区切りは (a)、グラフのページは (b)、プロセスのページは (c)、KPI のページは (e)、意思決定のページは (f) を使用します

(e) KPI コールアウト：大きな数字のカードグリッド

視覚的な結果。 1 行に大きな数字を 3 つまたは 4 つ並べます。各カードは、単位のサブラベル、小さな前年比変化率のチップ、1 行の要点で構成します。経営層向けのデッキで最も一般的な要素です。

サイズの目安。 60pt の Georgia ボールドは、幅 9.78cm のカードに約 5 文字（$84.2、118%、24.5）が収まります。$84.2M のように長い値は、$84.2 を大きな数字とし、USD millions をサブラベルに分けてください。単位の接尾辞に合わせてフォントサイズを縮小してはいけません。文字が折り返されるだけです。

グリッドの計算（カード 3 つ、左右の余白 1.5cm、間隔 0.76cm）: col_width = (33.87 − 3 − 1.52) / 3 = 9.78cm。x 座標は 1.5, 12.04, 22.58 です。リスクを一目で分かるように、「注意」を示すカード 1 枚にだけアクセントカラーを使用してください。

# Two cards: navy standard + terracotta watch. Each = bg + big number + sublabel + chip.
cat <<EOF | officecli batch "$FILE"
[
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"preset":"roundRect","fill":"1E2761","line":"none","x":"1.5cm","y":"4cm","width":"9.78cm","height":"7cm"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"84.2","x":"1.5cm","y":"4.8cm","width":"9.78cm","height":"2.8cm","font":"Georgia","size":"60","bold":"true","color":"FFFFFF","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"USD millions · ARR","x":"1.5cm","y":"8cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","color":"CADCFC","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"+24% YoY","x":"1.5cm","y":"9cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","bold":"true","color":"CADCFC","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"preset":"roundRect","fill":"B85042","line":"none","x":"22.58cm","y":"4cm","width":"9.78cm","height":"7cm"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"\$1.42","x":"22.58cm","y":"4.8cm","width":"9.78cm","height":"2.8cm","font":"Georgia","size":"60","bold":"true","color":"FFFFFF","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"CAC payback (yrs)","x":"22.58cm","y":"8cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","color":"FFFFFF","align":"center"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"text":"+8% — watch","x":"22.58cm","y":"9cm","width":"9.78cm","height":"0.8cm","font":"Calibri","size":"14","bold":"true","color":"FFFFFF","align":"center"}}
]
EOF

(f) 決定木：YES/NO の分岐

視覚的な結果。 上部中央にひし形を置き、YES と NO の子ボックスを左右に分岐させます。両者は共通の終端ボックスに収束させます。レイアウトは、ひし形を x=13.94, y=2cm, 6×3cm、YES を 3cm, 7.5cm、NO を 22.87cm, 7.5cm、終端を 13.94cm, 13cm に配置します。配色の規則は、赤＝停止／エスカレーション、青＝標準、緑＝安全な終端です。すべてのコネクタに矢じりが必要です。 矢じりがないと、読み手が進行方向を誤解します。

cat <<EOF | officecli batch "$FILE"
[
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Decide","preset":"diamond","fill":"1E2761","line":"none","x":"13.94cm","y":"2cm","width":"6cm","height":"3cm","text":"Hazardous energy present?","font":"Calibri","size":"14","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"YesBox","preset":"roundRect","fill":"B85042","line":"none","x":"3cm","y":"7.5cm","width":"8cm","height":"3cm","text":"Lockout + Tagout + Verify","font":"Calibri","size":"16","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"NoBox","preset":"roundRect","fill":"CADCFC","line":"none","x":"22.87cm","y":"7.5cm","width":"8cm","height":"3cm","text":"Proceed with standard PPE","font":"Calibri","size":"16","bold":"true","color":"1E2761","align":"center","valign":"middle"}},
  {"command":"add","parent":"/slide[$SLIDE]","type":"shape","props":{"name":"Done","preset":"roundRect","fill":"2C5F2D","line":"none","x":"13.94cm","y":"13cm","width":"6cm","height":"2.5cm","text":"Begin service","font":"Calibri","size":"16","bold":"true","color":"FFFFFF","align":"center","valign":"middle"}}
]
EOF

続けて、（c）のコネクタループのパターンを使い、4 本のコネクタ（Decide→YesBox、Decide→NoBox、YesBox→Done、NoBox→Done）を追加します。

QA（必須）

問題があると想定してください。 最初のレンダリング結果が正しいことはほとんどありません。問題が 1 件も見つからなかった場合は、十分に注意深く確認できていません。

配信ゲート（いずれかが失敗 = 却下、配信しないこと）

ゲート 1〜2b はテキストおよびスキーマレベルのチェックであり（レンダリングされたスライドは確認できません）、ゲート 3 が唯一の視覚的チェックです。完了の条件は、すべてのゲートが PASS であり、かつ ゲート 3 のループが収束していることです。

各ゲートは コマンドを実行し、その出力を判定する 形で行います。officecli のコマンドはどの OS（macOS / Linux / Windows）でも同一なので、シェルスクリプトは不要です。判定はご自身で行ってください。

• ゲート 1 — スキーマ。 officecli validate "<file>"。スキーマエラーがあれば却下して修正します。
• ゲート 2 — オーバーフロー / 書式 / 構造。 officecli view "<file>" issues。[O1]、[C1]、[S1] などのタグが付いた行が 一件でも 出力されたら却下し、修正して、問題がなくなるまで再実行します。
• ゲート 2b — 残存するプレースホルダー。 officecli view "<file>" text を実行し、出力に xxxx、lorem / ipsum、<TODO>、placeholder、「this slide layout」、または空の () / [] がないかを確認します。一件でも該当すれば却下します。

Gate 3 — ビジュアル監査（必須）

いずれか一つの方法を選んでください。

スクリーンショット（デフォルト） — 画像を認識できるエージェント向けです。officecli view "<file>" screenshot --page 1 -o slide1.png で各スライドを順番にスクリーンショットし、次に --page 2、… と続けてください。ページ番号がデッキの範囲を超えるまで繰り返します（スクリーンショット 1 枚 = スライド 1 枚）。ページ 1 でエラーになった場合は、下記のフォールバックを使用してください。

すべての PNG をチェックリストに照らし、敵対的に判定してください — 「問題は存在すると想定すること。問題が見つからないのは、十分に注意深く見ていないからである」という姿勢で臨みます。問題ごとに slide N: <issue> の行を 1 つ報告するか、問題がなければ PASS と報告してください。この手順は、どの方法で実行する場合でも必須です。ハーネスがサブエージェントを起動できる場合は、判定を新しく独立したサブエージェントに委任してください。デッキを作成したエージェントは「問題なさそう」というバイアスがかかっているため、別の目を持つ者のほうがより批判的に確認できます。スクリーンショットとこのチェックリスト、そして同じ敵対的な観点を渡してください。サブエージェントがない場合は、同じことを自分で行ってください。

フォールバック — HTML テキスト（画像認識ができない場合、またはスクリーンショットが失敗した場合）: view "$FILE" html をテキストとして読み込んでください。DOM では 暗い背景上の暗い要素 / 微細な重なり / 矢印の先端 / 余白や間隔の数値 / 列の整列 を証明できないため、これらは PASS とせず「視覚的に未検証」として記録してください。

任意の --grid N — レイアウトのリズムをユーザーが求めた場合、または view outline でレイアウト分布に異常が見られる場合にのみ使用します: officecli view "<file>" screenshot --grid 3 -o grid.png。

スライドごとのチェックリスト（問題が存在すると想定すること）:

• 重なり — 図形 / グラフ / 巨大な装飾数字（01/02/03 の 100pt 以上）の衝突
• テキストのはみ出し — スライドや図形の境界での切り取り（KPI カード、狭いボックス）
• 狭すぎるテキストボックス — 内容は収まっているが、短い行（1〜2 語ずつ）に多数折り返される場合。3cm の KPI カード内の長いサブラベル、窮屈な列内の本文行など
• 暗い背景上の暗い要素 — 塗りの明るさが 30% 未満で、テキストやアイコンの明るさが 80% 未満の場合（コントラストのある円がない暗いアイコンを含む）
• 画像の扱い — 写真の引き伸ばしや歪み、複雑な画像上にカードやスクリムなしで直接置かれたテキスト、スクリーンショットやロゴの切り抜き、白背景上に浮いて見える透過画像
• 矢印の先端の欠落 — フローチャートの接続線が単なる線になっている場合
• 装飾線とタイトルの不一致 — 一行のタイトル用に作られたアクセントバーに対して、タイトルが二行に折り返されている場合（またはその逆）
• フッター / 出典の衝突 — 出典行、ページ番号、脚注が上のコンテンツに接触している場合
• 余白・間隔の不足 — 要素がスライド端から約 0.5" 以内にある場合、または 2 つのカードが約 0.3" 以内にある場合
• 不均一な間隔 — 一方に大きな空白があり、もう一方が窮屈な場合（リズムの崩れ）
• 列・繰り返し要素の位置ずれ — KPI カードやアイコンがベースラインから外れている、または幅が不統一な場合
• 順序の妥当性 — 配列がストーリーと一致しているか（表紙 → アジェンダ → セクション前の区切り → 締めくくり）

問題があれば slide N: <issue> の行で却下し、問題がなければ「Gate 3 PASS」としてください（HTML テキストのフォールバックの場合は「 は視覚的に未検証」を追記）。

修正と再検証（必須、最大 3 サイクル）。 修正 → Gate 3 の再実行 → 新たな問題がなくなるまで繰り返してください。一つの修正が別の問題を表面化させることがよくあります。3 ラウンドを経ても収束しない場合は、停止してください。シーソー状態、テンプレートレベルの原因、またはエージェントの誤読の可能性があります。slide N: <issue> — attempted: <fixes> — likely root: <template|design-conflict|ambiguous> の形式で報告し、判断はユーザーに委ねてください。

その後のフラッシュ（ゲートの一部）。 Gate 3 が収束したら、officecli save "<file>" で締めくくってください。これにより、納品前に編集内容がディスクに書き込まれることが保証されます（単発のハンドオフでレジデントも解放したい場合は、代わりに officecli close "<file>" を使用してください）。これは任意ではなく必須の最終ステップです。常に安全で、エラーになったり作業内容を失ったりすることはありません。

よくある落とし穴

最初の試行でつまずきやすい点をまとめたチートシートです。デザインとシェルに関する罠を扱います。

落とし穴	正しい方法
zsh/bash で [N] をクォートしない	パスは必ずクォートしてください: "/slide[1]"。zsh はクォートされていない [1] をグロブとして展開し、no matches found になります。初回利用時に最もつまずきやすい点です
--name "foo"	すべての属性は --prop を経由します: --prop name="foo"
/shape[myname]（角括弧内の名前だけを指定）	@name= セレクターを使います: /shape[@name=myname] または /shape[@id=10007]
パスは 1 始まり、--index は 0 始まり	/slide[1] は最初のスライド、--index 0 は最初の位置を意味します
--prop text= 内の $	シングルクォートで囲みます: --prop text='$15M'。ダブルクォートの "$15M" はシェルに展開されて M になります
--prop text= 内の \n / \t	CLI によって解釈されます: \n は段落区切り、\t はタブです。リテラルとして扱うには \\n と二重にします