Organize translated docs and refine README demo thumbnails

.github/workflows/tools.yml

@@ -7,9 +7,9 @@ on:
       - "DemoLab/**"
       - "Localization/**"
       - "docs/**"
-      - "README*.md"
-      - "NOTICE*.md"
-      - "THIRD_PARTY_NOTICES*.md"
+      - "README.md"
+      - "NOTICE.md"
+      - "THIRD_PARTY_NOTICES.md"
       - "web/**"
       - ".github/workflows/tools.yml"
   workflow_dispatch:

DemoLab/README.md

@@ -1,5 +1,5 @@
 <!-- LANGUAGE-LINKS:START -->
-[English](README.md) · [한국어](ko/README.md) · [日本語](ja/README.md) · [简体中文](zh-Hans/README.md) · [繁體中文](zh-Hant/README.md)
+[English](README.md) · [한국어](docs/ko/README.md) · [日本語](docs/ja/README.md) · [简体中文](docs/zh-Hans/README.md) · [繁體中文](docs/zh-Hant/README.md)
 <!-- LANGUAGE-LINKS:END -->
 
 # Tatami Demo Lab
@@ -123,6 +123,8 @@ the image, with a chapter label at the upper left and actual keystrokes at the
 upper right. Translucent backgrounds keep text readable over light and dark apps.
 The colors come from the website palette; changing presentation needs no new capture.
 
+Poster frames use `posterSeconds` or `posterCaptionIndex` from `publication.json`. Choose a frame after the feature has taken effect. Poster URLs use the image hash so replacing a still does not require re-encoding its video.
+
 Caption edits may reuse an original only when every recorded action, typed input,
 assertion and delay is unchanged. The exporter verifies the frozen scene hash and
 compares those actions before replacing narration on the original timeline.

DemoLab/docs/SCENES.md

@@ -55,8 +55,8 @@ a reason to correct preparation, not to trim away the unexpected window later.
 | `virtualDisplay` | `connected` | Connect or disconnect the real guest virtual display helper. |
 | `configure` | `field`, `value` | Atomically edit an allowed live setting in the lab TOML. |
 | `clipboard` | `text` | Provide local example text, preserving and restoring all clipboard item types. |
-| `closeSettings` | — | Close the native settings window after authoring. |
-| `prepareSettings` | — | Size and position the native Tatami settings window before its controls are used. |
+| `closeSettings` | No fields | Close the native settings window after authoring. |
+| `prepareSettings` | No fields | Size and position the native Tatami settings window before its controls are used. |
 | `appWindows` | `app`, `count` | Set native window count, primarily for preparation. |
 
 There is no `appState` command. Views cannot be jumped to a pre-rendered success

DemoLab/ja/README.md → DemoLab/docs/ja/README.md

@@ -1,5 +1,5 @@
 <!-- LANGUAGE-LINKS:START -->
-[English](../README.md) · [한국어](../ko/README.md) · [日本語](README.md) · [简体中文](../zh-Hans/README.md) · [繁體中文](../zh-Hant/README.md)
+[English](../../README.md) · [한국어](../ko/README.md) · [日本語](README.md) · [简体中文](../zh-Hans/README.md) · [繁體中文](../zh-Hant/README.md)
 <!-- LANGUAGE-LINKS:END -->
 
 <a id="tatami-demo-lab"></a>
@@ -10,11 +10,11 @@
 <a id="publication-contract"></a>
 ## 公開用動画の規則
 
-[`publication.json`](../publication.json) が一覧と編集上限です。各場面を Web の区分に結び、時間とサイズを制限します。
+[`publication.json`](../../publication.json) が一覧と編集上限です。各場面を Web の区分に結び、時間とサイズを制限します。
 
 紹介動画はデザイン、執筆、レビュー、借りる操作、自動化から、実際の画面構成変更まで進みます。各動画集では作業、プロファイルと画面、配置とフォーカス、借りる操作、表示方法、CLI・フック、ガイドを扱います。一覧は `publication.json` から生成します。
 
-主動画は**作業を変えても元の場所に戻れる**ことを示します。機能別は別の活動を扱い、同じ動画を繰り返しません。[範囲と検証の境界](../docs/ja/COVERAGE.md)を参照してください。
+主動画は**作業を変えても元の場所に戻れる**ことを示します。機能別は別の活動を扱い、同じ動画を繰り返しません。[範囲と検証の境界](COVERAGE.md)を参照してください。
 
 <a id="capture--export--review--install-locally"></a>
 ## 録画 → 書き出し → 確認 → ローカル反映
@@ -85,6 +85,8 @@ GUEST_DIR=DemoLab/recordings/publish "$TOOL" vm-fetch-recordings DemoLab/recordi
 
 元の MOV には、撮影したデスクトップ全体が含まれます。書き出しは 1920×1200、2 画面の場合は 1920×600 です。説明字幕は映像の下部、章名は左上、実際のキー入力は右上に重ねます。半透明の背景により、明るいアプリでも暗いアプリでも読みやすくなります。色はウェブサイトの配色を使うため、表示の変更に再撮影は必要ありません。
 
+サムネイルの時点は、`publication.json` の `posterSeconds` または `posterCaptionIndex` で指定します。機能が実際に反映された後のフレームを選んでください。サムネイルの URL には画像のハッシュを使うため、画像だけを差し替える場合に動画を再エンコードする必要はありません。
+
 字幕の編集で元映像を再利用できるのは、撮影した操作、入力内容、検証条件、待機時間がすべて同じ場合だけです。書き出しツールは撮影時に固定したシーンのハッシュと操作を検証し、元のタイムライン上の説明文を差し替えます。検証資料には、編集前後のシーンとタイムラインを両方含めます。
 
 各テイクには次のファイルがあります。
@@ -99,7 +101,7 @@ GUEST_DIR=DemoLab/recordings/publish "$TOOL" vm-fetch-recordings DemoLab/recordi
 
 書き出しには再生ギャラリー、ポスター、検証用フレーム、元映像と出力のハッシュ、すべての付随ファイルが含まれます。自動検証だけでは実際の動作確認を代替できません。特に共有ウインドウのミラーリングとフォーカス先は目視確認が必要です。ウェブプレイヤーは標準コントロールと `preload="none"` を使い、手動で再生し、同時に再生する動画は一つです。各動画集にはサムネイル一覧、件数、前後のボタンがあります。各動画から関連する設定キーにも移動できます。矢印キー、Home/End、個別動画へのリンクは、一覧を別途展開せずに使えます。
 
-2 画面ではゲストに実際の仮想画面を接続し、別々に録画して最初の時刻で揃えます。[確認済み構成](../docs/ja/MULTI-DISPLAY.md)を参照してください。
+2 画面ではゲストに実際の仮想画面を接続し、別々に録画して最初の時刻で揃えます。[確認済み構成](MULTI-DISPLAY.md)を参照してください。
 
 <a id="work-on-one-scene"></a>
 ## 一つの場面を調整する
@@ -132,10 +134,10 @@ DEMOLAB_LOCALIZATION_DIR="$PWD/DemoLab/.build/DemoLab/Localization" \
   swift test --package-path DemoLab
 ```
 
-- [場面の語彙](../docs/ja/SCENES.md)
-- [VM の準備](../docs/ja/VM-TART.md)
-- [権限](../docs/ja/PERMISSIONS.md)
-- [実際の複数画面録画](../docs/ja/MULTI-DISPLAY.md)
+- [場面の語彙](SCENES.md)
+- [VM の準備](VM-TART.md)
+- [権限](PERMISSIONS.md)
+- [実際の複数画面録画](MULTI-DISPLAY.md)
 
 <a id="five-language-production"></a>
 ## 5 言語での制作

DemoLab/docs/ja/SCENES.md

@@ -48,8 +48,8 @@
 |`virtualDisplay`|`connected`|ゲストの実際の仮想画面ヘルパーを接続・切断します。|
 |`configure`|`field`, `value`|ラボの TOML で許可された設定を原子的に変更します。|
 |`clipboard`|`text`|クリップボードの全形式を保存・復元し、例文を渡します。|
-|`closeSettings`|—|編集後に設定ウインドウを閉じます。|
-|`prepareSettings`|—|コントロールを操作する前に、Tatami のネイティブ設定ウインドウのサイズと位置を整えます。|
+|`closeSettings`|フィールドなし|編集後に設定ウインドウを閉じます。|
+|`prepareSettings`|フィールドなし|コントロールを操作する前に、Tatami のネイティブ設定ウインドウのサイズと位置を整えます。|
 |`appWindows`|`app`, `count`|主に準備時に、実際のウインドウ数を設定します。|
 
 `appState` はありません。用意した成功画面へ飛ばず、通常の操作と `StoryRepository` で文章、レビュー、チェック、タスク、会話を同じ場所に保存します。`seed` でだけ初期化し、作業の切り替えでは戻しません。会話はネット接続のないローカル例です。
@@ -88,4 +88,4 @@
 
 `take` の既定値は `--overlay off` で、テキストは編集可能な ASS と JSON のサイドカーファイルに記録します。書き出した映像では、画面下部に字幕、左上にチャプター、右上に実際のキー入力を重ねます。半透明の背景で読みやすくしていますが、アプリの内容に重なるため、重要なコントロールはその領域を避けて配置してください。`scene` はライブのリハーサルパネルを使い、最終映像とは表示方法が異なります。
 
-配置と時間・容量上限は [publication.json](../../publication.json)、録画・出力・確認のコマンドは [README.md](../../ja/README.md) を参照してください。
+配置と時間・容量上限は [publication.json](../../publication.json)、録画・出力・確認のコマンドは [README.md](README.md) を参照してください。

DemoLab/ko/README.md → DemoLab/docs/ko/README.md

@@ -1,5 +1,5 @@
 <!-- LANGUAGE-LINKS:START -->
-[English](../README.md) · [한국어](README.md) · [日本語](../ja/README.md) · [简体中文](../zh-Hans/README.md) · [繁體中文](../zh-Hant/README.md)
+[English](../../README.md) · [한국어](README.md) · [日本語](../ja/README.md) · [简体中文](../zh-Hans/README.md) · [繁體中文](../zh-Hant/README.md)
 <!-- LANGUAGE-LINKS:END -->
 
 <a id="tatami-demo-lab"></a>
@@ -10,11 +10,11 @@
 <a id="publication-contract"></a>
 ## 공개용 영상 규칙
 
-[`publication.json`](../publication.json)에 영상 목록과 편집 예산을 정해요. 각 장면을 웹 섹션에 연결하고 길이와 파일 크기를 제한해요.
+[`publication.json`](../../publication.json)에 영상 목록과 편집 예산을 정해요. 각 장면을 웹 섹션에 연결하고 길이와 파일 크기를 제한해요.
 
 종합 영상은 디자인 → 글쓰기 → 검토 → 빌려오기 → 자동화에 이어 실제 화면 구성 변경으로 끝나요. 기능별 모음은 작업 공간, 프로필·화면, 타일링·포커스, 빌려오기, 창 표시, CLI·훅, 가이드 설정을 다뤄요. 목록은 `publication.json`에서 만들므로 별도로 중복 관리하지 않아요.
 
-종합 영상은 **작업을 바꿔도 하던 자리를 유지한다**는 약속을 보여줘요. 기능별 영상은 다른 활동을 보여주며 종합 영상을 반복하지 않아요. 전체 범위는 [기능과 검증 범위](../docs/ko/COVERAGE.md)에서 확인해요.
+종합 영상은 **작업을 바꿔도 하던 자리를 유지한다**는 약속을 보여줘요. 기능별 영상은 다른 활동을 보여주며 종합 영상을 반복하지 않아요. 전체 범위는 [기능과 검증 범위](COVERAGE.md)에서 확인해요.
 
 <a id="capture--export--review--install-locally"></a>
 ## 촬영 → 내보내기 → 검수 → 로컬 반영
@@ -85,6 +85,8 @@ GUEST_DIR=DemoLab/recordings/publish "$TOOL" vm-fetch-recordings DemoLab/recordi
 
 원본 MOV에는 촬영한 데스크톱 전체가 담겨요. 내보낼 때는 1920×1200을 유지하고, 두 화면 영상은 1920×600으로 만들어요. 자막은 영상 아래쪽에, 장면 이름은 왼쪽 위에, 실제 키 입력은 오른쪽 위에 겹쳐 표시해요. 반투명 배경으로 밝거나 어두운 앱 위에서도 읽기 쉽게 했어요. 색상은 웹사이트 팔레트를 사용하므로 표현을 바꿀 때 다시 촬영할 필요는 없어요.
 
+썸네일 시점은 `publication.json`의 `posterSeconds` 또는 `posterCaptionIndex`로 정해요. 기능이 실제로 적용된 뒤의 장면을 선택해요. 썸네일 URL에는 이미지 해시를 사용하므로 이미지만 교체할 때 영상을 다시 인코딩할 필요가 없어요.
+
 자막만 고칠 때는 촬영한 동작, 입력 내용, 검증 조건, 대기 시간이 모두 같아야 원본을 재사용할 수 있어요. 내보내기 도구는 촬영 당시 고정한 장면 파일의 해시와 동작을 검증한 뒤 원래 타임라인의 자막을 교체해요. 증거 자료에는 원본과 수정본의 장면 파일 및 타임라인을 모두 포함해요.
 
 각 테이크에는 다음 파일이 있어요.
@@ -99,7 +101,7 @@ GUEST_DIR=DemoLab/recordings/publish "$TOOL" vm-fetch-recordings DemoLab/recordi
 
 내보내기 묶음에는 재생 갤러리, 포스터, 추출한 검증 프레임, 원본·결과물 해시와 모든 부가 파일이 들어 있어요. 자동 검증이 실제 동작 확인을 대신하지는 않아요. 특히 공용 창 미러링과 포커스 대상은 화면으로 확인해야 해요. 웹 플레이어는 기본 컨트롤과 `preload="none"`를 사용하며, 직접 재생하고 한 번에 영상 하나만 재생돼요. 각 모음에는 썸네일 목록, 개수, 이전·다음 버튼이 있어요. 영상마다 관련 설정 키로 가는 링크도 제공해요. 방향키, Home/End, 개별 영상 링크는 별도 펼치기 없이 사용할 수 있어요.
 
-두 화면 촬영은 게스트에 실제 가상 디스플레이를 연결하고 각각 녹화한 뒤 첫 프레임 시각으로 맞춰요. [확인한 VM 구성](../docs/ko/MULTI-DISPLAY.md)을 참고하세요.
+두 화면 촬영은 게스트에 실제 가상 디스플레이를 연결하고 각각 녹화한 뒤 첫 프레임 시각으로 맞춰요. [확인한 VM 구성](MULTI-DISPLAY.md)을 참고하세요.
 
 <a id="work-on-one-scene"></a>
 ## 장면 하나 수정하기
@@ -132,10 +134,10 @@ DEMOLAB_LOCALIZATION_DIR="$PWD/DemoLab/.build/DemoLab/Localization" \
   swift test --package-path DemoLab
 ```
 
-- [장면 문법](../docs/ko/SCENES.md)
-- [VM 설정](../docs/ko/VM-TART.md)
-- [권한](../docs/ko/PERMISSIONS.md)
-- [실제 두 화면 촬영](../docs/ko/MULTI-DISPLAY.md)
+- [장면 문법](SCENES.md)
+- [VM 설정](VM-TART.md)
+- [권한](PERMISSIONS.md)
+- [실제 두 화면 촬영](MULTI-DISPLAY.md)
 
 <a id="five-language-production"></a>
 ## 다섯 언어 영상 제작

DemoLab/docs/ko/SCENES.md

@@ -48,8 +48,8 @@
 |`virtualDisplay`|`connected`|게스트의 실제 가상 화면 도구를 연결하거나 해제해요.|
 |`configure`|`field`, `value`|실험용 TOML의 허용한 설정을 원자적으로 바꿔요.|
 |`clipboard`|`text`|클립보드의 모든 데이터 형식을 백업·복원하며 예시 텍스트를 제공해요.|
-|`closeSettings`|—|편집 뒤 네이티브 설정 창을 닫아요.|
-|`prepareSettings`|—|컨트롤을 조작하기 전에 Tatami 설정 창의 크기와 위치를 맞춰요.|
+|`closeSettings`|필드 없음|편집 뒤 네이티브 설정 창을 닫아요.|
+|`prepareSettings`|필드 없음|컨트롤을 조작하기 전에 Tatami 설정 창의 크기와 위치를 맞춰요.|
 |`appWindows`|`app`, `count`|주로 준비 단계에서 실제 창 수를 정해요.|
 
 `appState` 명령은 없어요. 미리 만든 성공 화면으로 이동하지 않고 일반 컨트롤과 `StoryRepository`로 저장한 작업을 공유해요. 문구·검토·검사·할 일·메시지는 같은 제어 폴더에 저장해요. `seed`만 이야기를 초기화하고 공간 전환은 초기화하지 않아요. 대화는 네트워크 없는 로컬 데모예요.
@@ -88,4 +88,4 @@
 
 `take`의 기본값은 `--overlay off`이며, 텍스트는 편집 가능한 ASS와 JSON 부가 파일에 기록해요. 내보낸 영상은 화면 아래쪽에 자막을, 왼쪽 위에 챕터를, 오른쪽 위에 실제 키 입력을 겹쳐 보여줘요. 반투명 배경으로 가독성을 높이지만 앱 내용을 가릴 수 있으므로 중요한 컨트롤은 해당 영역을 피해서 배치해요. `scene`는 실시간 리허설 패널을 사용하며, 최종 영상의 표시 방식과는 달라요.
 
-배치 위치와 시간·용량 예산은 [publication.json](../../publication.json), 촬영·출력·검수 명령은 [README.md](../../ko/README.md)를 참고하세요.
+배치 위치와 시간·용량 예산은 [publication.json](../../publication.json), 촬영·출력·검수 명령은 [README.md](README.md)를 참고하세요.