arkorlab · soleil-colza · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/docs/cookbook/notifications.mdx b/docs/cookbook/notifications.mdx
@@ -5,10 +5,14 @@ description: "Post to a webhook when a training run finishes or fails, from insi
 
 # Slack / Discord notifications
 
-Training runs take long enough that nobody actually watches Studio the whole time. The terminal `onCompleted` and `onFailed` callbacks are perfect places to fan a status message out to wherever your team already lives.
+A training job is two waits back-to-back: GPU allocation at the start (variable, can be several minutes when a worker starts from cold; see the [Quickstart](/quickstart) for why) and then the training run itself (about 7 to 12 minutes for the templates). Nobody actually watches a browser tab for that long. The terminal `onCompleted` and `onFailed` callbacks are the natural spot to fan a status message out to wherever your team already lives so you only look back when the run is genuinely done.
 
 This recipe uses Slack incoming webhooks; Discord, Microsoft Teams, and arbitrary HTTP endpoints work the same way. Anything you can `fetch`, you can notify.
 
+<Note>
+If you only want a desktop ping for your own runs, Studio already shows a browser notification, an in-page toast, and a tab-title indicator on `training.completed` / `training.failed` once you click **Run training** (and accept the permission prompt). This recipe is for fanning the same signal into a shared channel.
+</Note>
+
 ## The pattern
 
 ```ts

diff --git a/docs/introduction.mdx b/docs/introduction.mdx
@@ -77,6 +77,6 @@ bun dev
 
 </CodeGroup>
 
-The first run finishes in roughly 7 to 12 minutes depending on the template.
+The training run itself takes about 7 to 12 minutes depending on the template. Arkor runs training on dedicated training GPUs that are not kept warm between jobs (inference uses a separate, always-warm pool, which is why the Playground stays snappy). When you start a training job, Arkor allocates a training GPU on demand: if one is still warm from a recent job it is ready in seconds, otherwise the worker has to start from cold, which can take several minutes. The [Quickstart](/quickstart) walks through what this looks like in Studio.
 
 Continue with the [Quickstart](/quickstart) for a step-by-step walkthrough.
diff --git a/docs/ja/cookbook/notifications.mdx b/docs/ja/cookbook/notifications.mdx
@@ -5,10 +5,14 @@ description: "学習が完了 or 失敗したときに、trainer.ts の中から
 
 # Slack / Discord 通知
 
-学習は長いので、ずっと Studio を見続ける人はいません。終端の `onCompleted` と `onFailed` コールバックは、チームが普段いる場所にステータスメッセージを流すのにうってつけです。
+学習ジョブは実質 2 つの待ちが続きます。最初に GPU の確保 (warm な GPU が残っていない場合は数分かかることもある cold start。理由は [Quickstart](/ja/quickstart) 参照)、次に学習本体 (テンプレートで約 7〜12 分)。ブラウザータブをそんなに長くは見ていられません。終端の `onCompleted` と `onFailed` コールバックは、チームが普段いる場所にステータスメッセージを流すのに自然な場所です。本当に完了したときだけ振り返ればよくなります。
 
 このレシピは Slack incoming Webhook を使います。Discord、Microsoft Teams、任意の HTTP エンドポイントも同じやり方で動きます。`fetch` できるものなら何でも通知先になります。
 
+<Note>
+自分のためのデスクトップ通知だけで十分なら、Studio が `training.completed` / `training.failed` 時にブラウザー通知・ページ内 toast・タブタイトルのインジケーターを出します (**Run training** をクリックして通知許可を受け入れた後で有効)。このレシピはそれをチームの共有チャンネルに飛ばすためのものです。
+</Note>
+
 ## パターン
 
 ```ts

diff --git a/docs/ja/introduction.mdx b/docs/ja/introduction.mdx
@@ -77,6 +77,6 @@ bun dev
 
 </CodeGroup>
 
-最初の実行は、テンプレートにもよりますがおおよそ 7〜12 分で終わります。
+学習本体はテンプレートにもよりますが約 7〜12 分です。Arkor は推論 (Inference) と学習 (Training) で別の GPU プールを使い分けており、推論側は常に warm な active worker 上で動くので Playground は即応します。一方の学習側はコストを安定させるため warm 維持しません。学習ジョブを開始すると、Arkor はそのときに学習用 GPU を確保しに行きます。直前のジョブで使われた直後など GPU がまだ warm な状態であれば確保は数秒で終わりますが、warm な GPU がなければ cold な状態から (プロビジョニング・コンテナイメージ取得・ベースモデルのロード) 立ち上げる必要があり、これに数分かかります。Studio 上で何が見えるかは [Quickstart](/ja/quickstart) で確認できます。
 
 ステップごとの手順は [Quickstart](/ja/quickstart) に続きます。
diff --git a/docs/ja/quickstart.mdx b/docs/ja/quickstart.mdx
@@ -3,7 +3,16 @@ title: "クイックスタート"
 description: "Arkor プロジェクトを生成し、小さなオープンウェイト LLM をファインチューニングして、ローカル Studio からチャットしてみる。"
 ---
 
-数分でゼロからスタートし、ローカル Playground でチャットできるファインチューン済みモデルが得られます。学習自体は 7〜12 分。セットアップ時間は回線と既存のインストール状況に左右されます。
+数分でゼロからスタートし、ローカル Playground でチャットできるファインチューン済みモデルが得られます。学習本体は 7〜12 分。最初に流すジョブは、学習本体が始まる前に GPU の確保 (立ち上がり) を待つ時間が入ります。これは数分かかることがあり、ときどきそれ以上かかります。間が空いた後の最初のジョブだけに発生する待ちです。セットアップ時間は回線と既存のインストール状況に左右されます。
+
+<Info>
+**Arkor が GPU をどう使い分けているか。** Arkor は GPU を 2 つのプールに分けて運用しています。
+
+- **推論 (Inference) 用 GPU。** 学習が終わったモデルで推論するための GPU です (Playground や本番の推論)。active worker 上に常駐させているので、いつでも warm な状態で即座に応答します。
+- **学習 (Training) 用 GPU。** ファインチューニング用の GPU です。コストを安定させるため warm 維持はしません。**Run training** を押すと、その時点で GPU を確保しに行きます。直前に他のジョブで使われた直後など、GPU がまだ warm な状態であれば確保は数秒で終わります。warm な GPU がなければ cold な状態 (プロビジョニング・コンテナイメージ取得・ベースモデルのロード。いわゆる cold start) から立ち上げる必要があり、これに数分かかります。
+
+GPU が確保できた後、学習本体自体はテンプレートにより約 7〜12 分です。Studio の Jobs 画面では両フェーズが可視化されます。
+</Info>
 
 ## 前提条件
 
@@ -41,11 +50,11 @@ cd my-arkor-app
 
 プロジェクト生成ツールがどのテンプレートを使うか尋ねてきます。最終的に作りたいものに最も近いものを選んでください:
 
-| テンプレート | タスク                  | 出力の形                                              | 推定学習時間 |
-| ------------ | ----------------------- | ----------------------------------------------------- | ------------ |
-| `triage`     | サポートのトリアージ    | `{ category, urgency, summary, nextAction }`          | 約 7 分      |
-| `translate`  | 9 言語の翻訳            | `{ translation, detectedLanguage }`                   | 約 7 分      |
-| `redaction`  | 個人情報のマスク        | `{ redactedText, redactedCount, tags }`               | 約 12 分     |
+| テンプレート | タスク                  | 出力の形                                              | 学習本体 (GPU 確保時間を除く) |
+| ------------ | ----------------------- | ----------------------------------------------------- | ----------------------------- |
+| `triage`     | サポートのトリアージ    | `{ category, urgency, summary, nextAction }`          | 約 7 分                       |
+| `translate`  | 9 言語の翻訳            | `{ translation, detectedLanguage }`                   | 約 7 分                       |
+| `redaction`  | 個人情報のマスク        | `{ redactedText, redactedCount, tags }`               | 約 12 分                      |
 
 いずれも同じ小型のオープンウェイトベース（`gemma-4-E4B-it`）と、HuggingFace 上の厳選された公開データセットを組み合わせたものです。学習は本物で、数分で終わるので、ループ全体をエンドツーエンドで体験できます。
 
@@ -119,7 +128,7 @@ bun dev
 学習が進行中に重要なビューは 3 つあります:
 
 - **Jobs。** 学習ジョブの一覧。クリックするとライブステータスが見られます。
-- **Loss チャートとイベントログ。** マネージド GPU から進捗がストリームされるにつれて、Loss（学習中のモデルの誤差を示す数値で、低いほどモデルが正解に近づいているサイン）の曲線が更新され、ログのテールに学習イベントが表示されます。最初の学習はテンプレートにより 7〜12 分かかります。
+- **Loss チャートとイベントログ。** マネージド GPU から進捗がストリームされるにつれて、Loss（学習中のモデルの誤差を示す数値で、低いほどモデルが正解に近づいているサイン）の曲線が更新され、ログのテールに学習イベントが表示されます。最初のジョブの最初のフェーズは GPU の確保で、その間ステータスは `Warming up GPU` と表示され、Loss チャートは `Waiting for GPU` のプレースホルダー、イベントログは空のままです。`training.started` イベントが届くとステータスが `Running` に変わり、曲線が更新を始めます。学習本体自体はテンプレートにより 7〜12 分かかります。
 - **Playground。** ジョブが完了したら、最終アダプタをセレクタから選んでチャット。モード切替でベースモデルとアダプタを行き来できます。学習中に中間チェックポイントで推論を走らせたい場合は Studio ではなく `onCheckpoint` コールバックを使ってください。
 
 学習の合間に `src/arkor/` を編集した場合は、Run training ページをリロード（または `arkor build` を実行）してから次のクリックをすると、新しいコードが動きます。

diff --git a/docs/ja/studio/jobs.mdx b/docs/ja/studio/jobs.mdx
@@ -21,13 +21,24 @@ Run training パネルはページ読み込み時に `/api/manifest` を 1 度
 
 トレーナー選択やフラグを渡す入力フォームはありません: Studio は常に `createArkor` で登録されたトレーナーを走らせ、`arkor start` は `.arkor/build/index.mjs` があれば再利用します。同じページで複数回クリックする間に `src/arkor/` の編集は自動では拾われません。編集の合間に Run training ページをリロード（あるいはターミナルから `arkor build`）してから次のクリックをしてください。具体的なリビルドルールは [CLI § build / start](/ja/cli/build-and-start) を参照。
 
+### 「最初のジョブ」で起きていること
+
+**Run training** をクリックすると、2 つのフェーズが続きます:
+
+1. **GPU の確保。** ジョブは `Warming up GPU` と表示されます。Loss チャートは `Waiting for GPU` のプレースホルダー、イベントリストは空のままで、Metadata サイドバーの **Phase** 行は `Warming up GPU`、**GPU warm-up** タイマーが動きます。このフェーズの時間は状況次第です。直前のジョブで warm な状態の GPU が残っていれば普通は 1 分以内ですが、cold な状態から立ち上げる必要がある場合は数分かかることがあります。なぜそうなるかは [Quickstart](/ja/quickstart) を参照。
+2. **学習本体。** `training.started` が届くとステータスが `Running` に変わり、Loss チャートが `training.log` フレームから更新を始め、**Phase** 行が `Training run` になります。これが Quickstart のテンプレート表にある 7〜12 分のウィンドウです。
+
+<Tip>
+**Run training** はブラウザータブをフォアグラウンドにしてからクリックしてください。Studio が通知許可をブラウザーに求め、ジョブが完了または失敗したときにデスクトップ通知とタブタイトルのインジケーターを表示するので、タブを見張る必要がなくなります。
+</Tip>
+
 ## Jobs リスト
 
 Jobs リストはマウント時に 1 度、その後 5 秒ごとに `GET /api/jobs` をポーリングします。手動リフレッシュボタンはなく、間隔は固定です。
 
 | 列 | ソース |
 | --- | --- |
-| Status | `Job.status`（`queued` / `running` / `completed` / `failed` / `cancelled`）。セルは色付け用の CSS クラスを持つ。 |
+| Status | `Job.status`（`queued` / `running` / `completed` / `failed` / `cancelled`）に、Studio 側のリスト表示で 1 つの表示ステートを足したもの。`createdAt` が直近 90 秒以内の `queued` ジョブは `Warming up GPU` として表示される。リスト画面は `/api/jobs` のポーリングだけで SSE は開かないため、ここでは createdAt の窓だけで判定する。Job 詳細では同じルールに加えて SSE ストリームの接続状態も加味される。セルは色付け用の CSS クラスを持つ。 |
 | Name | `Job.name`。`#/jobs/<id>` にリンク。 |
 | Created | `new Date(Job.createdAt).toLocaleString()`。 |
 | ID | `Job.id`、等幅フォント。 |

diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
@@ -3,7 +3,16 @@ title: "Quickstart"
 description: "Scaffold an Arkor project, fine-tune a small open-weight LLM, and chat with it from a local Studio."
 ---
 
-In a few minutes you will go from zero to a fine-tuned model you can chat with in a local Playground. The training itself takes 7 to 12 minutes; setup time depends on your connection and what is already installed.
+In a few minutes you will go from zero to a fine-tuned model you can chat with in a local Playground. The training run itself takes 7 to 12 minutes. The first job you submit also waits for a GPU to be allocated before the training run starts; that wait can be a few minutes (occasionally longer) and only happens for the first run after a quiet period.
+
+<Info>
+**How Arkor uses GPUs.** Arkor splits GPUs into two pools:
+
+- **Inference GPUs** run the model after training (the Playground and any production inference). These stay on an active worker, so they are always warm and respond immediately.
+- **Training GPUs** run fine-tuning jobs. To keep costs predictable, these are not kept warm. When you click **Run training**, Arkor allocates a GPU on demand. If a worker is still warm from a recent job, the allocation finishes in seconds. Otherwise it starts from cold (the so-called cold start: provisioning, pulling the container image, loading the base model), which can take several minutes.
+
+After GPU allocation, the training run itself takes about 7 to 12 minutes for the templates. The Jobs view in Studio shows both phases.
+</Info>
 
 ## Prerequisites
 
@@ -41,11 +50,11 @@ cd my-arkor-app
 
 The scaffolder asks which template you want. Pick the one closest to what you eventually want to build:
 
-| Template    | Task                    | Output shape                                          | Estimated training |
-| ----------- | ----------------------- | ----------------------------------------------------- | ------------------ |
-| `triage`    | Support triage          | `{ category, urgency, summary, nextAction }`          | ~7 min             |
-| `translate` | 9-language translation  | `{ translation, detectedLanguage }`                   | ~7 min             |
-| `redaction` | PII redaction           | `{ redactedText, redactedCount, tags }`               | ~12 min            |
+| Template    | Task                    | Output shape                                          | Training run (excludes GPU allocation) |
+| ----------- | ----------------------- | ----------------------------------------------------- | -------------------------------------- |
+| `triage`    | Support triage          | `{ category, urgency, summary, nextAction }`          | ~7 min                                 |
+| `translate` | 9-language translation  | `{ translation, detectedLanguage }`                   | ~7 min                                 |
+| `redaction` | PII redaction           | `{ redactedText, redactedCount, tags }`               | ~12 min                                |
 
 Each template pairs the same small open-weight base (`gemma-4-E4B-it`) with a curated public dataset on HuggingFace. The training is real and finishes in minutes, so you get to see the whole loop end to end.
 
@@ -119,7 +128,7 @@ In the browser, click **Run training**. Studio submits the job to the managed ba
 Once a run is in flight, three views matter:
 
 - **Jobs.** A list of training runs. Click into one to see live status.
-- **Loss chart and event log.** As the run streams from the managed GPU, the loss curve updates and the log tail shows training events. The first run takes 7 to 12 minutes depending on the template.
+- **Loss chart and event log.** As the run streams from the managed GPU, the loss curve updates and the log tail shows training events. The first job's first phase is the GPU allocation; during that time the status reads `Warming up GPU`, the loss chart shows a `Waiting for GPU` placeholder, and the events list is empty. Once the `training.started` event arrives, the status flips to `Running` and the curve begins to update. The training run itself takes about 7 to 12 minutes depending on the template.
 - **Playground.** After a job completes, pick the final adapter from the selector and chat with it. Use the mode toggle to switch between the base model and the adapter. To run inference on intermediate checkpoints while a run is still in flight, use `onCheckpoint` callbacks instead of Studio.
 
 If you edit `src/arkor/` between runs, refresh the Run training page (or run `arkor build`) before the next click so the new code is what runs.