基本の考え方

KUMODeckは、バイブコーディングのためのフラットなバックエンドです（Webアプリ・ゲームなど）。ホスティング・データベース・ログインは、いつも使っているAIエージェントに言葉で頼むと、エージェントが用意します。中身はプロジェクト、環境、鍵、プレイヤー（利用者のこと。APIの名前ではplayers）、マスターデータの5つで説明できます。その上に3つの約束があります。使いたい部分だけを選べること、利用者に見えるのはKUMODeckではなくあなたのアプリであること、そして作ったものはあなたのものであることです。

フラットなバックエンド#

KUMODeckは、Webアプリやゲームに要る部品を用意し、アプリの前には何も置きません。データベースと自分のサーバーのプログラム（Functions）、マルチプレイ、ログイン（ゲストを含む）、クラウドセーブ、独自ドメインでのホスティング、Xでのシェア、そしてそのすべてをAIエージェント（Claude Code・Codexなど）から操作できること。アプリの上に何かをかぶせることはありません。ストアの入口も、利用者の前に出るKUMODeckの名前もありません。マルチプレイのルームやゲーム向けのSkillはゲームのためのもので、アプリなら使わなければよいだけです。

だれが何を受け持つか#

KUMODeckが守るのは、壊れたときにあなたや利用者が困るところです。何をどう作るかはあなたのものなので、自由に作れます。KUMODeckがその良し悪しを決めることはありません。

ランキングなどのゲーム向けの機能は、Skillで作る#

ランキングのようなゲーム向けの機能は、KUMODeckのサービスではありません。自分のデータベースとFunctionsの上に作ります。AIエージェントに頼めば、テンプレートに入っているランキングのSkill（.claude/skills/leaderboard/SKILL.md）がコードを組み立てます。コードもデータもルールもあなたのものなので、ゲームに合わせて好きなように変えてください。

必要なものだけを選ぶ#

どの機能も単独で動きます。ホスティングだけ、セーブだけ、データベースだけを使うこともできますし、アプリを自分でホスティングして何も使わないこともできます。課金されるのは使ったものだけで、原価どおりです（料金）。

データの置き場所: 守るものは D1 に。saves には入れない。 利用者が自分で書き換えてはいけないもの（スコアとランキング・コイン・クレジット・アイテム・購入・バッジ・利用者どうしで共有するもの）は、プロジェクト自身の Functions + D1 に置く。saves に置くのは、利用者が自由に書いてよいもの（設定・下書き・1 人で遊ぶゲームの進み具合）だけ。 迷ったら: 利用者が手で書き換えると困るなら、自分のデータベースです。どこに何を置くかの表はセーブとFunctionsにあります。

使うたびにお金がかかるもの、またはプレイヤーに見えるものを変えるものは、ONにするまで動きません。

それ以外（セーブ、ルーム）は、アプリが呼び出すか設定で宣言したときにだけ動きます。

KUMODeckではなく、あなたのアプリ#

KUMODeckはCDNのようなインフラです。利用者に見えるのは、あなたのアプリやゲーム、あなたのURL、Xでのあなたのカードです。利用者に見えるものにKUMODeckの名前は出ません。配信するページ、カード画像、共有リンク、Functionsの応答、ログインのメール（プロジェクトの名前で届きます）、利用者が目にしうるエラーメッセージには、KUMODeckのブランド表示がありません。

プロジェクト#

プロジェクトは1つのアプリやゲームです。kumodeck initかダッシュボードで作ります。名前とslug（URLに使う名前。英小文字・数字・ハイフン1つずつ。--は予約済み）を持ち、1つの開発者アカウントに属します。kumodeck initはコードの隣にkumo.json（projectId、slug、api）を書きます。秘密情報は含まないので、コミットしてかまいません。

環境#

どのプロジェクトにもdevelopmentとproductionの2つの環境があり、実行時には何も共有しません。

テストの操作が本物の利用者のデータに混ざることはなく、設定の試行錯誤もproductionにpushするまで本物の利用者には届きません。

鍵#

環境ごとに2種類のAPIキーがあります。環境は鍵そのものに含まれるので、鍵が別の環境を操作することはありません。

SDKは秘密鍵を渡されるとその場でエラーにします。鍵が平文で表示されるのは作成時の一度だけで、サーバーはハッシュしか保存しません。入れ替えはダッシュボードで行います（新しい鍵を作る→デプロイする→古い鍵を失効させる）。

開発者本人（ダッシュボードとCLI）は、これとは別の開発者セッション（kds_…）で認証します。

プレイヤー#

プレイヤーは、あなたのアプリやゲームの利用者1人のことです（APIとSDKではplayers・playerIdのようにplayerと呼びます）。1つのプロジェクトの1つの環境の中だけに存在し、KUMODeckがプロジェクトをまたいで利用者を追跡することはありません。

• Kumo.init()は初回に自動でゲストとしてログインし、次回からは同じゲストを復元します（リフレッシュトークンは公開鍵ごとにlocalStorageへ保存）。
• ゲストは後からメールを連携（auth.linkEmail）でき、セーブはそのまま残ります。以後は別の端末からauth.signInWithEmailでログインできます。
• セッションは15分のアクセストークン（JWT）と、90日の回転式リフレッシュトークンです。使用済みのリフレッシュトークンが再提示されると系列ごと失効します（盗難対策）。SDKは更新を自動で行い、ブラウザのタブ同士でも調整します。
• BANされたプレイヤーは、ログイン・更新・書き込みのたびに拒否され、接続中のリアルタイム通信も切断されます。

マスターデータ（kumo.config.json）#

サーバーがプロジェクトに守らせるルールは、コードではなく宣言で書きます。

kumodeck config push（またはダッシュボードの編集）で反映します。pushのたびに全体を検証して版を付けます。内容が同じなら版は増えません。アプリは公開部分（GET /v1/gamedata/definitions）を読めますが、適用するのはサーバーだけです。改造されたクライアントがそれを変えることはできません。詳細は設定リファレンスを参照してください。