Cluebase setup documents

Cluebase 導入は analytics のタグ埋め込みではありません。観測された事実を Customer Value Understanding Engine へ渡し、後続の value_achievement、diagnosis、next_action へつながる証拠経路を作る作業です。

顧客側の変更は、対象runtimeの公式SDKを導入し、既存アプリの起動・認証・組織・session resetの境界へ公式APIを必要最小限だけ追加することです。transport、token、OpenTelemetry/自動収集、相関、送信失敗の隔離はCluebase SDKが担当します。

• 対象runtimeの公式Cluebase SDKを依存管理へ追加する。server runtimeでAPI keyまたはservice keyが必要な場合はserverだけに設定し、frontendへ渡さない。
• 起動時に `cluebase.init` を一度だけ呼び、既存の認証・組織・session resetの境界に `identify`・`group`・`reset` を追加する。`track` は自動収集で取れない明確な業務イベントを顧客が明示する場合だけ使い、自動挿入しない。
• 通常のアプリ操作でCluebase導入が顧客アプリを妨げないことを確認する。

• Cluebase SDK が本番コードの通常経路に接続されている。
• frontend/backendの全対象serviceが、対象runtimeに対応する公開Cluebase SDKを宣言している。
• secret が server 側に残り、client bundle に含まれない。
• user と organization の識別が既存 auth 状態に追従する。
• logout または session reset で Cluebase 側の identity がクリアされる。
• 通常のアプリ操作でCluebase導入が顧客アプリを妨げないことを確認し、必要に応じて任意の診断を利用する。

• SDK は事実を観測して送る入口です。
• AI analysis や diagnosis を導入先アプリ内で固定実装しない。
• Cluebase 側で observation、operation、value_achievement、evidence_bundle、next_action へ発展できるように、識別情報と context を欠落させない。
• event name や URL だけに依存せず、user、organization、environment、page context を送れる状態にする。

• 観測された事実と AI の判断を host app 側で混ぜない。
• unknown page や unknown operation でも送信が壊れないようにする。
• 特定顧客、特定画面、特定 URL 前提の分岐を追加しない。
• Cluebase の canonical model を壊す新しい用語を作らない。

`ObservationSourceEvent -> observation -> operation -> value_achievement -> flow_progress / value_claim / diagnosis -> customer_value_state -> evidence_bundle -> next_action` を正とします。

• `CLUEBASE_API_KEY` または `CLUEBASE_SERVICE_KEY`: 対象runtimeの公式SDKが要求する場合だけ、host backendのsecretとして設定します。frontend code、HTML、public env、mobile bundleには置きません。
• `CLUEBASE_PROJECT_KEY`: 対象runtimeの公式SDKが要求する場合に設定します。
• API base URL / endpoint は任意です。接続先を変更しない場合は設定せず、SDKの既定値 `https://api.cluebase.io` を使います。
• server only の値は `.env`、secret manager、hosting provider の server secret に置きます。

• `NEXT_PUBLIC_CLUEBASE_PROJECT_KEY` (Vite なら `VITE_CLUEBASE_PROJECT_KEY`) は必須のpublic project keyです。
• `NEXT_PUBLIC_CLUEBASE_API_BASE_URL` (Vite なら `VITE_CLUEBASE_API_BASE_URL`) は接続先を変える場合だけ置く任意のpublic envです。未指定時はSDKの既定値 `https://api.cluebase.io` を使い、server-onlyの `CLUEBASE_*` secretは置きません。
• 既存のpublic runtime設定機構がない場合は、Cluebase専用の環境ファイルを作らず、既存の起動・設定ファイルへ公開project keyだけを最小限記述します。

Cluebase は Stripe publishable key / Mixpanel project token / Sentry DSN と同じ業界標準パターンで、 frontend SDK が public 識別子を持って Cluebase backend と直接通信します。 顧客 backend に Cluebase 専用 route を作る必要はありません。

短命 token に origin claim を bind + HMAC 署名 + 期限 を含めて発行し、 ingest 時には Origin header と claim を再検証することで CSRF / 他 origin からの abuse を防御しています。 安全な公開設計です。

• `CLUEBASE_API_KEY` を frontend code、HTML、public env、mobile bundle に入れない。
• browser から secret を使って Cluebase API を直接呼ばない。
• setup のために一時的に secret を console に出さない。

• app root、layout、provider、client bootstrap、main entry。
• API server startup、middleware registration、plugin registration。
• login callback、session restore、auth provider success handler。
• organization を確定する provider または hook。
• logout、sign out、session clear、token revoke の実装。

• 既存の auth source of truth に従う。
• organization switch がある場合は switch 後の確定値を使う。
• route path や button text だけで user identity を決めない。
• 未ログイン状態では identify せず、匿名観測に留める。

初回導入の customer repository に Cluebase SDK importやdependencyが存在しないのは正常です。公式契約に従って対象runtimeの公式SDKを導入し、既存の起動・lifecycle境界へ必要最小限のAPIを追加します。

既存の auth、organization、reset、bootstrap の境界は repository から判断しますが、SDK package 名、関数 signature、env 名、 frontend SDK と Cluebase backend の通信方向は Cluebase の公式契約を source of truth とします。

• dependency: `@genn-inc/cluebase-frontend-sdk@latest`
• import: `import cluebase from "@genn-inc/cluebase-frontend-sdk"`
• `cluebase.init(options)` は app 起動時に一度だけ呼ぶ。endpointは任意で、未指定時は `https://api.cluebase.io` を使う。SDKがtransport、token、event送信を内蔵するため、顧客backendにCluebase専用routeを作る必要はない。
• `cluebase.identify(userId, traits)` はログイン済み user id を受け取り、表示名がある場合は `traits.name` に入れる。
• `cluebase.group("organization", organizationId, traits)` は会社 id を受け取り、表示名がある場合は `traits.name` に入れる。
• `cluebase.reset()` は session reset 後に呼ぶ。
• frontendから顧客backendへリクエストを送る場合は、実際のbackend originを `tracePropagationOrigins` に設定する。Cluebase API originを指定してはいけない。
• public lifecycle API は SDK 内で failure isolation されるため、各呼び出しを独自 try/catch で囲まない。

• dependency: `cluebase-backend-sdk`。Python backend dependency は version pin しない。
• import: `from cluebase_backend_sdk import cluebase`
• FastAPI app 作成後に `cluebase.init(...)` を一度だけ呼ぶ。初期化には対象SDKの契約で必要な `project_key`、`api_key`、`service_key` のみを渡し、endpointは接続先を変える場合だけ任意で指定します。
• `cluebase.identify(user_id, traits={...})`, `cluebase.group("organization", organization_id, traits={...})`, `cluebase.reset()` を既存 lifecycle 境界で呼ぶ。
• API base URL / endpointは接続先を変える場合だけ任意で設定します。未指定時はbackend SDKが `https://api.cluebase.io` を使います。

• Cluebase固有のsource、config、environment、adapter fileは作成しない。公式SDKのimport、初期化、API呼び出しは既存のアプリケーションファイルへ最小限だけ追加する。
• 顧客 backend に Cluebase 専用 route は作らない。 frontend SDK が Cluebase backend を直接叩く設計のため、 host backend に追加する Cluebase 関連 route は 0 個。
• 既存の関数、変数、クラス、route、cookie、認証、session、tenant/organization処理を改名、削除、移動、分割、統合、wrapper化、挙動変更しない。
• 顧客側で独自のmiddleware、proxy、経由route、HTTP client、独自transport、logger、exporter、OpenTelemetry設定、runtime preload、browser build plugin、framework adapter、zone/polyfillを追加しない。公式SDKの初期化が内部で登録する処理は公式SDKの責務とする。
• 顧客側の変更は package.json または同等の依存管理ファイル、lockfile、既存のアプリケーション・環境設定ファイルへの最小追記に限定し、host appのauth redesign、router redesign、formatter cleanup、独自transportを混ぜない。

Cluebase frontend SDK は Stripe.js (publishable key) / Mixpanel JS SDK (project token) / Segment Analytics.js (write key) / Sentry JavaScript SDK (DSN) と同じ「public 識別子 + origin allowlist」 業界標準パターンで動きます。 顧客 backend に Cluebase 専用 route を追加実装する必要はありません。

frontend は framework に合う public env 名で必須のproject keyを持ちます。API base URLはローカルなど接続先を変える場合だけ任意で設定し、未指定時はSDKの既定値 `https://api.cluebase.io` を使います。Next.js は `NEXT_PUBLIC_CLUEBASE_PROJECT_KEY` / `NEXT_PUBLIC_CLUEBASE_API_BASE_URL`、Vite は `VITE_CLUEBASE_PROJECT_KEY` / `VITE_CLUEBASE_API_BASE_URL` を使い、SDK内蔵でCluebase backendを直接呼びます。

• hop 1: 顧客 frontend → Cluebase backend `POST /api/v1/ingest/browser-tokens` で短命 frontend token を取得 (= SDK が自動で叩く)。
• hop 2: 顧客 frontend → Cluebase backend `POST /api/v1/ingest/browser` で frontend event を ingest (= SDK が自動で叩く)。
• hop 3: 顧客 backend → Cluebase backend `POST /api/v1/ingest/backend` で server event を ingest (= backend SDK が `x-cluebase-api-key` 付きで叩く)。

• token は Cluebase backend が発行する短命 token で、 origin claim bind + HMAC 署名 + 期限 を含みます。
• ingest 時に Cluebase backend が token を再検証し、 同時に request の Origin header と claim の origin が一致するか確認します (= 他 origin からの abuse 防御)。
• `CLUEBASE_API_KEY` (secret) は backend SDK のみが使用し、 frontend bundle / public env には絶対に出ません。
• projectKey は public 識別子で、 Stripe publishable key と同じく漏れても安全な設計です。

Cluebase backend 側の `POST /api/v1/ingest/browser-tokens` が origin allowlist + projectKey 検証で短命 token を発行します。

顧客 backend は frontend event 送信の token 発行責務を持ちません。frontend SDK が Cluebase backend を直接呼びます。

• frontend では既存のmodule-level client singleton、SPA entry、またはframeworkのclient startup boundaryで一度だけ呼びます。
• Next.js で既存のclient startup boundaryを使う場合は、必要に応じて `"use client"` から始まる既存ファイルへ追加します。
• backend では server startup、framework plugin registration、middleware registration のタイミングで呼びます。
• React component の `useEffect`、page component、sidebar、auth callback の中では呼ばず、component rerender ごとに再実行しないようにします。

• `CLUEBASE_API_KEY` を `cluebase.init` の frontend side option に渡さない (= frontend SDK は public projectKey のみで動く)。
• 必須のproject keyが欠けている場合は `cluebase.init` に空文字を渡さず、不足を報告する。endpointは任意で、Next.js は `NEXT_PUBLIC_CLUEBASE_API_BASE_URL`、Vite は `VITE_CLUEBASE_API_BASE_URL` を使う。
• singleton guard を使う場合、`initialized = true` は `cluebase.init` 呼び出し後に設定する。
• init failure を host app の起動失敗にしない。
• 複数 root がある場合は root ごとではなく実行単位ごとに一度にする。

• login success 後、または session restore で user が確定した後。
• user id が変わったとき。
• 匿名状態から認証済み状態へ遷移したとき。

• `userId`: host app の安定 user id。
• `traits.email`: 存在する場合のみ。PII の扱いは host app の方針に従う。
• `traits.name`、`traits.role`、`traits.plan` など、価値理解に役立つ範囲の属性。

• 未ログインの仮 id を userId として固定しない。
• route 名や email だけで user id を作らない。
• logout 後は前 user の identity を残さない。

• organization が確定した後。
• organization switch が完了した後。
• session restore で active organization が復元された後。

• user id と organization id を混同しない。
• organization switch の前の値で `cluebase.group` を呼ばない。
• 個別画面の path から organization id を推測しない。

• logout button の成功処理。
• session expired で user state を消す処理。
• user switch の前。
• test organization から real organization へ切り替える前。

• logout failure 時に host app の session 状態と矛盾しないようにする。
• identity clear は user-facing error にしない。
• organization だけ切り替える場合は `cluebase.group`、user 自体が消える場合は `cluebase.reset` を使う。

• フォーム送信、決済完了、動画完了など、画面のclickやnetworkだけでは成功を判定できないとき。
• 既存の自動収集で同じ事実を取得できる場合はtrackを追加せず、重複を避ける。
• 成功したことが確定した後にだけ呼び、開始・失敗・途中状態は別の意味として設計できる場合に限って追加する。

• イベント名やpropertiesにpassword、token、API key、決済情報などのsecretを入れない。
• 自動収集で取得済みのpage view、click、networkをtrackで重複送信しない。
• trackの失敗を顧客アプリの業務処理へ伝播させない。

• frontendの同意バナーで、ユーザーが許可または拒否を選択した直後。
• 保存済みの同意状態を復元した直後。initより前にopt-inを要求する場合はdeniedを設定してからinitする。
• backendではプロセス単位の運用スイッチが必要な場合だけ使う。個別ユーザーの同意管理を代用するAPIではない。

• 同意状態を実際の同意管理UIや既存のconsent sourceと接続する。
• denied後に送信が止まることを確認する。すでにnetworkへ渡ったrequestは取り消せない。
• Cluebaseが不要な場合にsetConsentを機械的に追加せず、対象アプリの同意要件に合わせる。

• 通常の自動batch送信で十分な場合は追加しない。
• ページ離脱前、重要な業務イベントの直後、短時間でprocessが終了する処理など、送信完了を待つ必要がある場合。
• flush後もSDKは開いたままなので、その後のイベント収集を継続できる。

• flushを各イベントの後に呼ぶとbatchingの利点を失うため、必要な境界にだけ置く。
• flushの失敗を顧客アプリの業務成功・失敗判定に使わない。結果を確認する必要がある場合はSDK diagnosticsを使う。

• backend processのgraceful shutdownや、SDKを再利用しないworker終了時。
• 通常のSPAの画面遷移やNext.jsのrenderごとには使わず、必要ならflushを使う。
• closeはflushとリソース解放をまとめて行うため、終了境界で一度だけ呼ぶ。

• close後に同じSDK instanceで収集を再開しない。別の実行単位で再開する場合だけinitから開始する。
• closeはディスクへの永続化を保証するAPIではなく、期限内のbest-effort送信です。

• linkはbackendで外部サービスIDと自社のcanonical subjectを実際に対応付ける必要がある場合だけ使う。browserでは使わない。
• operation discriminatorは既にOTelで観測されているrequestの分岐をCode Evidenceと結び付ける場合だけ使う。業務イベントの代わりにしない。
• diagnosticsはpayload、credential、header、raw PIIを含まないため、SDKの状態確認やdoctorの補助に使う。

• linkはExternalIdentityRelationを自動承認せず、既存のscope・revision・collision・human reviewを迂回しない。
• operation discriminatorにユーザー入力やsecretを入れない。
• diagnosticsの内容をログや顧客向け画面へ無制限に公開しない。

• `src/lib/cluebase.ts` などの client singleton で `cluebase.init` を一度だけ呼び、`app/layout.tsx` からその module を読み込む。
• Cluebase 用の `app/api/v1/cluebase/...` route は **作らない**。Next.js では frontend SDK が Cluebase backend を直接叩くため、`NEXT_PUBLIC_CLUEBASE_API_BASE_URL` と `NEXT_PUBLIC_CLUEBASE_PROJECT_KEY` を public env に置くだけで完結する。
• auth callback、session provider、user hook の user 確定後に `cluebase.identify` を呼ぶ。
• organization provider の確定後に `cluebase.group("organization", ...)` を呼ぶ。
• signOut handler、logout route、session clear callback で `cluebase.reset` を呼ぶ。

• server runtime の設定にだけ `CLUEBASE_API_KEY` が出現する。
• client bundle に `CLUEBASE_API_KEY` が出現しない。
• login restore 後に identify が呼ばれる。
• organization switch 後に organization が更新される。

• `src/main.tsx` または root provider に bootstrap component を置く。
• Cluebase 用 backend route は **作らない**。frontend SDK が Cluebase backend を直接叩くため、SPA に backend がなくても Cluebase 導入は可能。
• auth provider の user 確定後に `cluebase.identify` を呼ぶ。
• organization provider の確定後に `cluebase.group("organization", ...)` を呼ぶ。
• logout handler で `cluebase.reset` を呼ぶ。

• SPA に backend がなくても Cluebase 導入は可能です。frontend SDK が Cluebase backend を直接叩くため、BFF や proxy を追加実装する必要はありません。
• public env に置くのは Cluebase API base URL と public projectKey だけにする。 `CLUEBASE_API_KEY` は backend SDK 専用で frontend に出さない。
• React Strict Mode の development double effect で破綻しないよう、SDK 側の idempotency に従う。

• `AppComponent` または root provider の singleton 初期化箇所で `cluebase.init` を一度だけ呼ぶ。
• Cluebase 用 backend route は作らない。frontend SDK が Cluebase backend を直接叩く。
• auth service の user 確定後に `cluebase.identify` を呼ぶ。
• organization service の確定後に `cluebase.group("organization", ...)` を呼ぶ。
• logout handler で `cluebase.reset` を呼ぶ。

• browser bundle に入れるのは Cluebase API base URL と public projectKey だけにする。
• `CLUEBASE_API_KEY` は frontend SDK option や browser bundle に入れない。
• Angular SSR を使う場合も browser SDK 初期化は browser 側 singleton に閉じる。

• `main.py` または app factory で `cluebase.init` を一度だけ呼ぶ。
• auth dependency で request user が確定した後に `cluebase.identify` を呼ぶ。
• organization dependency の確定後に `cluebase.group` を呼ぶ。
• logout endpoint で `cluebase.reset` を呼ぶ。
• frontend がある場合でも FastAPI に Cluebase 用 route を **追加実装しない**。frontend SDK が Cluebase backend を直接叩き、backend SDK 側は通常の server event ingest のみ担当する。

• dependency が every request で呼ばれる場合、SDK の推奨する request context に従う。
• API key を frontend response に含めない。
• background task で user context が必要な場合は明示的に引き継ぐ。

• `settings.py`、`AppConfig.ready`、または project startup で `cluebase.init` を一度だけ呼ぶ。
• login view、auth signal、session restore middleware で user 確定後に `cluebase.identify` を呼ぶ。
• organization middleware または request scoped organization resolver で `cluebase.group` を呼ぶ。
• logout view で `cluebase.reset` を呼ぶ。
• frontend がある場合でも Django view に Cluebase 用 route を **追加実装しない**。frontend SDK が Cluebase backend を直接叩き、backend SDK 側は通常の server event ingest のみ担当する。

• middleware order は auth middleware と organization resolver の後に置く。
• anonymous user を authenticated user として identify しない。
• Django template に `CLUEBASE_API_KEY` を出さない。

• `setup-check` で顧客repositoryのSDK構成を確認し、`setup-doctor` はCluebaseの疎通と顧客アプリから届いた実イベント・自動収集・保存・分析入力を確認する。synthetic疎通だけでは完了扱いにしない。
• `CLUEBASE_API_KEY` が server-only の場所にだけある。
• frontend/backendの全対象serviceが、対象runtimeに対応する公開Cluebase SDKを使っている。
• `cluebase.init`、`cluebase.identify`、`cluebase.group`、`cluebase.reset` の接続点がある。
• framework の root、auth、organization、logout の既存経路に接続されている。
• テストまたは手動確認の根拠が残っている。

• `setup-doctor` は実画面操作の前に使う疎通確認です。
• 確認する hop は 3 つです: (1) `client frontend -> Cluebase /api/v1/ingest/browser-tokens` (= frontend SDK が短命 token を取得)、 (2) `client frontend -> Cluebase /api/v1/ingest/browser` (= frontend event 送信)、 (3) `client backend -> Cluebase /api/v1/ingest/backend` (= server event 送信、 `x-cluebase-api-key` 付き)。
• setup-doctor は login/logout/organization 操作の代替ではありません。event delivery の最終確認は developer が setup 画面または ClickHouse canonical readback で行います。

• 実操作確認は、developer がブラウザで login、organization switch、logout を操作できる状態で行います。
• AI agent が勝手に production user 操作を代行してはいけません。
• 確認結果が failed の場合は、どの接続点が欠けているかを report に残します。

• `CLUEBASE_API_KEY` を frontend SDK option や browser bundle に入れない。
• secret を console、HTML、test snapshot に出さない。
• 顧客 backend に browser token 用 endpoint を作らない。

• 特定 URL、特定 page、特定 organization だけで成立する分岐を入れない。
• auth が確定する前に fake user として identify しない。
• organization id と user id を同じ値で代用しない。
• logout 接続を後回しにしない。
• AI diagnosis や next_action を host app 側で固定生成しない。

• 未確認なのに完了と報告しない。
• build success を setup success と同一視しない。
• runtime check をしていない場合は `未確認` と書く。