プロジェクト構成

my-arkor-app/
├── src/arkor/
│   ├── index.ts        # createArkor({ trainer })
│   └── trainer.ts      # createTrainer({ ... })
├── arkor.config.ts
├── AGENTS.md           # AI コーディングエージェント向けの指示（create-arkor / arkor init の --no-agents-md で無効化）
├── CLAUDE.md           # 生成時のデフォルト内容: @AGENTS.md の 1 行再エクスポート
├── .arkor/             # プロジェクトごとの状態（gitignore 済み）
└── package.json        # dev / build / start

​

src/arkor/

1. export const arkor = createArkor({ trainer })（推奨。テンプレートが生成する形）。
2. export const trainer = createTrainer({ ... })（パワーユーザー向けショートカット。ラッパーが不要な場合）。
3. デフォルトエクスポート（Arkor マニフェスト or Trainer のいずれか）。

// src/arkor/index.ts（推奨形）
import { createArkor } from "arkor";
import { trainer } from "./trainer";

export const arkor = createArkor({ trainer });

// src/arkor/trainer.ts
import { createTrainer } from "arkor";

export const trainer = createTrainer({
  name: "support-bot-v1",
  model: "unsloth/gemma-4-E4B-it",
  dataset: { type: "huggingface", name: "arkorlab/triage-demo" },
  lora: { r: 16, alpha: 16 },
  maxSteps: 100,
});

​

arkor.config.ts

// arkor.config.ts
export default {};

​

.arkor/（プロジェクトごと、gitignore 済み）

• .arkor/state.json。プロジェクトのルーティング: orgSlug、projectSlug、projectId。これによってランタイムはローカルリポジトリをマネージドバックエンドのワークスペースにマップします。ファイルは ensureProjectState() が作成し、CLI や Studio がスコープを必要とする最初のアクション（学習の開始、ベースモデル推論、Studio の Endpoints ページからの初回 deployment 作成など）で走ります。純粋な read 経路（Endpoints / Jobs の一覧表示など）は意図的に初期化を起こさないので、新規チェックアウト直後に Studio を開いてもリモートにプロジェクトを副作用で作ったりせず、空一覧が表示されるだけです。匿名ワークスペースではこの初回 write 呼び出しで自動作成されます。OAuth ワークスペースの場合はランタイムがエラーを返します。今のところ arkor login も arkor init もこのファイルに値を書き込まないので、{ orgSlug, projectSlug, projectId } を手動で書いて作るのが現実的な方法です。一度作られた後は手で編集しないでください。 arkor logout 後の注意点: logout は credentials.json だけを削除するため、前の匿名 ID が残した .arkor/state.json はそのまま残ります。次の匿名セッションは新しい組織になり、read 経路ではこの古いファイルを無視します（一覧は空のまま、Studio も開けます）が、上記の write 経路は（手動管理された OAuth スコープの可能性があるため）それを再利用も上書きもせず、409／エラーで「.arkor/state.json を削除して新しい匿名プロジェクトを開始するか、そのプロジェクトを所有するアカウントで arkor login してください」と案内して失敗します。
• .arkor/build/index.mjs。arkor build の出力。src/arkor/index.ts を Node 22.22 ターゲットで esbuild した単一バンドルで、bare specifier は外部のままにしてあります。arkor start がこれを実行します。

​

~/.arkor/（ユーザーごと）

• ~/.arkor/credentials.json。認証状態。arkor login --oauth または対話的な arkor login のピッカーで OAuth (browser) を選んだ場合に書かれる Arkor Cloud OAuth トークンか、未ログインで初使用時に作られる匿名トークンのいずれか。ファイルは mode フィールドが "oauth" か "anon" でタグ付けされており、CLI はどのモードにいるかを把握します。arkor login はこのファイルだけを書きます。.arkor/state.json は 作成しません。
• ~/.arkor/studio-token（一時的）。arkor dev が起動ごとに書く CSRF トークン（モード 0600）。Studio が CLI のローカルサーバーへの呼び出しを認可するのに使います。arkor dev 起動のたびにローテートされます。

​

CLI が探すもの

• arkor dev は Studio の Web サーバーを 127.0.0.1:4000 で起動し、~/.arkor/studio-token を書きます。src/arkor/ をファイル監視はしません。Studio の /api/manifest エンドポイントは確かに runBuild を呼び、bundle の content-addressed コピー経由で再 import します（無編集の再読込は Node のモジュールキャッシュを再利用し、編集はキャッシュをバストします）が、それは Studio UI が fetch したときだけです（現状は Run training ページのマウント時）。同じページに留まったまま学習を複数回実行すると、ビルド成果物は再利用されます。編集した後は Run training ページをリロード（あるいはターミナルから arkor build）して変更を取り込んでください。arkor dev は単独で .arkor/state.json を書きません。
• arkor build は src/arkor/index.ts（または渡したエントリー）を読んで .arkor/build/index.mjs を書きます。Studio の dev ループの外側で直接呼ぶ必要があるのは CI や、スクリプトから arkor start の直前に走らせる場合などです。
• arkor start はランナー経由でエントリーを解決し、.arkor/build/index.mjs がない、もしくは明示的なエントリーを渡したときはリビルドして実行します（これが trainer.start() と trainer.wait() を呼びます）。Studio から学習をトリガーすると内部的に arkor start がサブプロセスとして起動されます。