@unson/brainbase-mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,22 +1,24 @@
-# Brainbase Personal Onboarding Kit
+# Brainbase 個人オンボーディングキット
 
-Brainbase is a local-first MCP server for handing your personal source of truth to AI coding tools.
+Brainbaseは、自分が承認した仕事の前提をCodex、Claude Code、CodeCodeへ渡すための、ローカル優先のMCPサーバーです。
 
-The v1 value is narrow by design: create a canonical local SSOT for yourself, your work, relationships, and decisions, then expose it through MCP tools that Codex, Claude, and CodeCode can call.
+最初の目標は情報源をすべて接続することではありません。自分、仕事、関係者、判断基準の最小文脈を保存し、10分以内に「同じ前提を説明し直さず役立つ出力」を確認することです。
 
-Ontology 1.0.0 adds a portable semantic contract on top of those local files. It defines types, relation vocabulary, validation constraints, deterministic decision inference, and version-evolution guidance without requiring a hosted Brainbase service.
+Ontology 1.0.0は、ローカルファイルへ持ち運べる意味契約を追加します。ホスト型Brainbaseを必要とせず、型、関係語彙、検証制約、決定論的な判断推論、バージョン移行を定義します。
 
-This repository does not include the internal Brainbase UI, session runtime, xterm transport, workflow mission control, social operations, hosted backend, Infisical setup, or Unson internal data. Those belong in the internal `brainbase-unson` system.
+このリポジトリに、社内BrainbaseのUI、セッション実行基盤、xterm転送、ワークフロー管制、SNS運用、ホスト型バックエンド、Infisical設定、雲孫の社内データは含みません。それらは社内版`brainbase-unson`の範囲です。
 
-## Manual
+## マニュアル
 
 Read the public onboarding manual at [brainbase.pages.dev](https://brainbase.pages.dev/). It guides users through five phases: choose one real use case, register approved work context, prove the first value, add only necessary sources, and operationalize Skills, routines, and MCP.
 
+For the shortest safe path, open [10分で試す](https://brainbase.pages.dev/guide/quick-start). It keeps the first prompt, MCP setup, optional Judgment Host setup, verification, and interruption recovery in one resumable checklist.
+
 The manual is the best starting point for first-time users. It explains Brainbase concepts, the first onboarding flow, MCP registration, project context setup, source onboarding, daily routines, and CLI reference.
 
-## Agent-assisted Onboarding
+## エージェントと始める
 
-Brainbase is designed to be adopted from Codex, Claude Code, or CodeCode. The first onboarding goal is a useful answer from your own context, not connector setup.
+BrainbaseはCodex、Claude Code、CodeCodeから導入できます。最初に目指すのは接続設定ではなく、自分の文脈を使った役立つ出力です。
 
 ```bash
 npm install
@@ -24,9 +26,19 @@ npm run build
 npm run onboard:start -- --target codex
 ```
 
-`onboard:start` is the Japanese first-run entrypoint for agent-assisted onboarding. It creates the minimum Personal OS directory, but it does not save self, project, relationship, decision, mail, calendar, drive, or task facts until the user approves them. It asks Codex or Claude Code what context you do not want to explain repeatedly, then shows the first prompt to try, the expected value, the minimum seed command, `onboard:demo`, project registration, optional source diagnosis, candidate review, MCP install, and `doctor`. The demo command appears before source diagnosis.
+`onboard:start`は日本語の初回導入コマンドです。最小ディレクトリだけを作り、本人、プロジェクト、関係者、判断、メール、カレンダー、ドライブ、タスクの事実は、利用者が承認するまで保存しません。通常表示は次の一手だけに絞り、全項目は`--details`で確認できます。
+
+公開CLIをインストール済みなら、次の3ステップです。
+
+```bash
+brainbase onboard:start --target codex
+# 表示された onboard:seed を確認して実行
+brainbase onboard:demo --scenario "実際に試す依頼"
+```
+
+リポジトリをcloneした場合は、同じ流れを`npm run onboard:start -- --target codex`、表示された`npm run`コマンド、`npm run onboard:demo -- --scenario "実際に試す依頼"`で進めます。
 
-If the user says "I want to onboard Brainbase", the agent should run this flow instead of returning a checklist. The expected sequence is: build if needed, run `onboard:start`, ask for the smallest context the user wants Brainbase to remember, seed only approved facts, then run `onboard:demo` with a real request. The agent must show the prompt, sample result, what the user no longer had to explain, and the still-unfinished operationalization work. `ready: true`, `first_value_demo_ready`, generated skills, generated routines, and `onboard:install --dry-run` are not completion signals by themselves.
+利用者がBrainbaseの導入を依頼したら、エージェントはチェックリストを返すだけでなく、この公開CLIを実行します。最小文脈を確認し、承認された事実だけを`onboard:seed`で保存し、現実の依頼で`onboard:demo`を実行します。プロンプト、出力、説明し直さずに済んだ前提、まだ終わっていない運用化を分けて示します。`ready: true`、`first_value_demo_ready`、Skillsやルーティンの生成、`onboard:install --dry-run`だけでは導入完了ではありません。
 
 For a Google Workspace / Google Drive / local-notes setup, pass the known answers and let the command surface what still needs approval:
 
@@ -354,6 +366,7 @@ brainbase onboard:routines --target codex --cwd /path/to/brainbase
 brainbase onboard:skills --target codex
 brainbase ontology:show
 brainbase ontology:audit
+brainbase judgment:install --target codex --dry-run
 brainbase doctor
 ```
 
@@ -373,6 +386,7 @@ node dist/cli.js onboard:apply --from <candidate-file> --select <id> --write
 node dist/cli.js onboard:routines --target codex --cwd "$(pwd)"
 node dist/cli.js onboard:skills --target codex
 node dist/cli.js onboard:recommend --email gmail --calendar google-calendar --drive google-drive --tasks notion
+node dist/cli.js judgment:install --target codex --dry-run
 npm run onboard:init
 npm run onboard:seed -- --name "Your Name"
 npm run onboard:install -- --target codex --dry-run
@@ -390,6 +404,44 @@ brainbase onboard:seed \
   --relationship "Key Partner|collaborator|Works with me on AI adoption"
 ```
 
+## Judgment Resolver Host for Codex
+
+Brainbase includes a local Judgment Resolver core and a Codex lifecycle Host adapter. The Host starts one portable episode at `UserPromptSubmit`, appends ordered tool events at `PostToolUse`, and finalizes the same episode at `Stop`. It builds one canonical context, adopts exactly one receipt for the turn, and gives the model only the selected judgment nodes and audit contract to follow. The full route receipt remains in the local journal instead of being injected into model context. It does not call a hosted Brainbase service, require a secret, or check project access.
+
+Preview the Codex `UserPromptSubmit`, `PostToolUse`, and `Stop` hook snippet:
+
+```bash
+brainbase judgment:install --target codex --dry-run
+```
+
+Review and merge all three printed event bindings into `~/.codex/hooks.json`. The command is preview-only unless `--output` is provided; it never merges into or overwrites an existing config. To save a new snippet file before reviewing it:
+
+```bash
+brainbase judgment:install --target codex --output /tmp/brainbase-judgment-hooks.json
+```
+
+Preserve unrelated hooks, then verify the installed bindings and start a new Codex task:
+
+```bash
+brainbase doctor --dir ~/.brainbase/personal-os --judgment-hooks ~/.codex/hooks.json
+```
+
+After installation, the Host instructs the AI to begin every user-facing response with an exact owner-visible audit line such as:
+
+```text
+🧠 判断参照: 直前の「ログイン後の白画面を直して」を参照 → 実装依頼として継続 ✓
+```
+
+The line identifies the concrete current or prior user statement used as judgment evidence and the decision made from it. The excerpt is collapsed to one line, limited to 26 Unicode characters, and redacts secret-like assignments and token formats. For example, a question may show `「この仕組みを説明して」を参照 → 質問として回答 ✓`; an unresolved follow-up shows `⚠️ 判断参照: 「それでいい」の対象を特定できず → 確認質問` instead of looking like a successful resolution.
+
+Judgment evidence and knowledge-call evidence are separate. A `🧠 判断参照` line says which request the Resolver judged; it never proves that an MCP lookup happened. The Host emits `📚` only after an actual successful portable MCP call and emits `⚠️` for `isError`, malformed, or empty CallToolResult envelopes. The portable mappings are `get_context` → routing (`Brainbase参照先`), `search` → search (`Brainbase検索`), and `search_personal_kg` → retrieval (`Brainbase取得`). Source selection and exclusions appear only when the tool result contains them. When a turn requires no knowledge lookup and none occurred, the exact audit is `📚 Brainbase未参照: 必須参照なし・実呼び出し0回 ✓`; a knowledge-required turn cannot use that line to satisfy retrieval.
+
+Detailed receipts, ordered tool events, the final event snapshot, and the exact owner-visible line are journaled together under `~/.brainbase/personal-os/judgment-journal/`, keyed by session and turn. Replayed tool events with the same `tool_use_id` and content are idempotent; conflicting reuse, corrupt journals, and a `Stop` without a matching active episode fail loudly. Only one receipt is adopted for a turn, and later duplicate hook calls reuse the stored line instead of rendering a possibly different summary. The line reports Resolver judgment evidence; it does not claim that Personal OS knowledge was already retrieved.
+
+At `Stop`, the Host verifies that all expected audit lines appear at the beginning, exactly once, and in journal order. The first repairable failure returns one bounded block instruction and binds the non-audit answer body by digest. If the active repair changes that body or still omits the required audit contract, the hook exits nonzero with `judgment_stop_repair_exhausted` instead of completing the episode.
+
+Every turn is judged, including questions and follow-up instructions. If a follow-up has no usable referent, the receipt selects clarification and the AI asks what the user meant; it does not refuse merely because classification or project context is incomplete. A receipt is judgment evidence, not permission to write files, send messages, deploy, purchase, or perform any other external effect. Normal host permissions and user approvals still apply.
+
 ## Install MCP Config
 
 Dry-run output:

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 interface CliIo {
+    stdin?: AsyncIterable<string | Uint8Array>;
     stdout?: {
         write(chunk: string): unknown;
     };
@@ -8,4 +9,5 @@ interface CliIo {
     };
 }
 export declare function runCli(argv?: string[], io?: CliIo): Promise<number>;
+export declare function isCliEntrypoint(moduleUrl: string, invokedPath: string | undefined): boolean;
 export {};

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { constants } from 'node:fs';
+import { constants, realpathSync } from 'node:fs';
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { delimiter, dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -8,15 +8,20 @@ import { resolveDataDir } from './paths.js';
 import { auditPersonalOsDirectory } from './ontology-ssot.js';
 import { portableOntology, resolveOntologyVersion } from './ontology.js';
 import { onboardingStatus } from './tools.js';
-import { buildCandidateDrafts, parseOnboardingFormat, renderAgentProtocol, renderCandidateDrafts, renderConnectorRecommendations, renderLocalOnboardingPlan, renderSourceDiagnosis, renderValueDemo } from './onboarding.js';
+import { buildCandidateDrafts, buildValueDemo, parseOnboardingFormat, renderAgentProtocol, renderCandidateDrafts, renderConnectorRecommendations, renderLocalOnboardingPlan, renderSourceDiagnosis, renderValueDemo } from './onboarding.js';
 import { buildExtractedCandidateSet, extractCandidates, loadApplyCandidates, normalizeSource, parseProvider, planApply, renderSourceJsonl, sourcePathFor } from './import-extract.js';
 import { buildClaudeScheduledTasks, buildRoutines, parseRoutineKinds, parseRoutineTarget, renderCodexAutomations } from './routines.js';
 import { assertPublicSafeSkillBundle, buildSkillBundle, parseSkillIds, parseSkillTarget, renderSkillsMarkdown } from './skills.js';
 import { buildProjectRegistrationPlan, parseProjectSource, parseProjectStakeholder, renderProjectRegistrationMarkdown } from './projects.js';
 import { renderGuidedFirstRun } from './guided-onboarding.js';
+import { blockedJudgmentOutput, processJudgmentHook } from './judgment-host.js';
 export async function runCli(argv = process.argv.slice(2), io = process) {
     const parsed = parseArgs(argv);
     try {
+        if (parsed.flags.has('help')) {
+            write(io, usage());
+            return 0;
+        }
         switch (parsed.command) {
             case 'onboard:init':
                 return await onboardInit(parsed, io);
@@ -55,6 +60,10 @@ export async function runCli(argv = process.argv.slice(2), io = process) {
                 return 0;
             case 'ontology:audit':
                 return await ontologyAudit(parsed, io);
+            case 'judgment:hook':
+                return await judgmentHook(io);
+            case 'judgment:install':
+                return await judgmentInstall(parsed, io);
             case 'doctor':
                 return await doctor(parsed, io);
             case 'mcp':
@@ -70,6 +79,59 @@ export async function runCli(argv = process.argv.slice(2), io = process) {
         return 1;
     }
 }
+async function judgmentHook(io) {
+    let payload = {};
+    try {
+        const input = await readHookStdin(io.stdin ?? process.stdin);
+        payload = JSON.parse(input || '{}');
+        write(io, `${JSON.stringify(await processJudgmentHook(payload))}\n`);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const eventName = payload.hook_event_name ?? payload.hookEventName;
+        if (eventName === 'Stop' && payload.stop_hook_active === true) {
+            writeError(io, `${reason}\n`);
+            return 1;
+        }
+        write(io, `${JSON.stringify(blockedJudgmentOutput(reason))}\n`);
+    }
+    return 0;
+}
+async function judgmentInstall(parsed, io) {
+    const target = first(parsed, 'target');
+    if (target !== 'codex')
+        throw new Error('judgment:install currently requires --target codex');
+    const cliPath = fileURLToPath(new URL('./cli.js', import.meta.url));
+    const hook = {
+        hooks: [{
+                type: 'command',
+                command: `${JSON.stringify(process.execPath)} ${JSON.stringify(cliPath)} judgment:hook`,
+                statusMessage: 'brainbase judgment resolver'
+            }]
+    };
+    const payload = `${JSON.stringify({
+        hooks: {
+            UserPromptSubmit: [hook],
+            PostToolUse: [hook],
+            Stop: [hook]
+        }
+    }, null, 2)}\n`;
+    const outputPath = first(parsed, 'output');
+    if (parsed.flags.has('dry-run') || !outputPath) {
+        write(io, payload);
+        return 0;
+    }
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeConfigSnippet(outputPath, payload);
+    write(io, `Wrote Codex Judgment Host config snippet to ${outputPath}\n`);
+    return 0;
+}
+async function readHookStdin(input) {
+    let text = '';
+    for await (const chunk of input)
+        text += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+    return text;
+}
 async function onboardInit(parsed, io) {
     const dataDir = resolveDataDir(first(parsed, 'dir'));
     await initializePersonalOs(dataDir);
@@ -78,8 +140,21 @@ async function onboardInit(parsed, io) {
 }
 async function onboardSeed(parsed, io) {
     const dataDir = resolveDataDir(first(parsed, 'dir'));
-    await initializePersonalOs(dataDir);
     const name = first(parsed, 'name');
+    const encodedRelationships = parsed.values.get('relationship') ?? [];
+    for (const encoded of encodedRelationships) {
+        const [person, , context] = encoded.split('|').map((part) => part.trim());
+        if (!person || !context) {
+            throw new Error([
+                '関係者の形式が正しくありません。',
+                '形式: "人|役割|覚えておく文脈"',
+                '例: "田中|責任者|Atlas導入の最終判断を担当"',
+                '保存内容は変更していません。',
+                `再実行: ${seedRetryCommand(parsed, dataDir, encoded)}`
+            ].join('\n'));
+        }
+    }
+    await initializePersonalOs(dataDir);
     const hasSeedValues = Boolean(name)
         || ['value', 'project', 'decision-principle', 'relationship'].some((key) => (parsed.values.get(key)?.length ?? 0) > 0);
     if (!parsed.flags.has('non-interactive') && !hasSeedValues) {
@@ -88,8 +163,8 @@ async function onboardSeed(parsed, io) {
     }
     await mutatePersonalOs(dataDir, (os) => {
         const now = new Date().toISOString();
-        const personalEntries = [];
-        const decisions = [];
+        const personalEntries = [...os.personalKg];
+        const decisions = [...os.decisions];
         const relationships = [...os.relationships.relationships];
         const graphEntities = [...os.graph.entities];
         if (name) {
@@ -98,19 +173,19 @@ async function onboardSeed(parsed, io) {
                 id: 'self',
                 type: 'person',
                 name,
-                summary: 'Owner of this local Brainbase Personal OS.',
+                summary: 'このPersonal OSの本人。',
                 tags: ['self']
             });
-            personalEntries.push({
-                id: `self-${Date.now()}`,
+            upsertById(personalEntries, {
+                id: `self-${hash(name)}`,
                 type: 'self',
-                text: `I am ${name}.`,
+                text: `私は${name}です。`,
                 tags: ['self'],
                 updatedAt: now
             });
         }
         for (const value of parsed.values.get('value') ?? []) {
-            personalEntries.push({
+            upsertById(personalEntries, {
                 id: `value-${hash(value)}`,
                 type: 'value',
                 text: value,
@@ -123,10 +198,10 @@ async function onboardSeed(parsed, io) {
                 id: `project-${hash(project)}`,
                 type: 'project',
                 name: project,
-                summary: 'Seeded during Brainbase onboarding.',
+                summary: '現在取り組んでいるプロジェクト。',
                 tags: ['work']
             });
-            personalEntries.push({
+            upsertById(personalEntries, {
                 id: `work-${hash(project)}`,
                 type: 'work',
                 text: project,
@@ -135,20 +210,17 @@ async function onboardSeed(parsed, io) {
             });
         }
         for (const value of parsed.values.get('decision-principle') ?? []) {
-            decisions.push({
+            upsertById(decisions, {
                 id: `decision-${hash(value)}`,
-                title: 'Seeded decision principle',
+                title: 'オンボーディングで登録した判断基準',
                 decision: value,
                 tags: ['principle', 'onboarding'],
                 updatedAt: now
             });
         }
-        for (const encoded of parsed.values.get('relationship') ?? []) {
+        for (const encoded of encodedRelationships) {
             const [person, role, context] = encoded.split('|').map((part) => part.trim());
-            if (!person || !context) {
-                throw new Error('relationship must be "person|role|context" or "person||context"');
-            }
-            relationships.push({
+            upsertById(relationships, {
                 id: `relationship-${hash(encoded)}`,
                 person,
                 role: role || undefined,
@@ -167,13 +239,46 @@ async function onboardSeed(parsed, io) {
         return proposedPersonalOs(os, {
             graph: { ...os.graph, entities: graphEntities },
             relationships: { version: 1, relationships },
-            personalKg: [...os.personalKg, ...personalEntries],
-            decisions: [...os.decisions, ...decisions]
+            personalKg: personalEntries,
+            decisions
         });
     });
-    write(io, `Seeded Brainbase Personal OS at ${dataDir}\n`);
+    const summary = [
+        `Brainbaseへ保存しました: ${dataDir}`,
+        ...(name ? [`- 本人: ${name}`] : []),
+        ...(parsed.values.get('value') ?? []).map((value) => `- 価値観: ${value}`),
+        ...(parsed.values.get('project') ?? []).map((project) => `- プロジェクト: ${project}`),
+        ...encodedRelationships.map((encoded) => {
+            const [person, role] = encoded.split('|').map((part) => part.trim());
+            return `- 関係者: ${person}${role ? `（${role}）` : ''}`;
+        }),
+        ...(parsed.values.get('decision-principle') ?? []).map((value) => `- 判断基準: ${value}`),
+        '- 同じ文脈は更新しました。既存の別データは削除していません。',
+        '',
+        '次に実行:',
+        `brainbase onboard:demo --dir ${shellArg(dataDir)} --scenario "保存した文脈を使って、次に進めるメモを作って"`,
+        ''
+    ];
+    write(io, summary.join('\n'));
     return 0;
 }
+function seedRetryCommand(parsed, dataDir, invalidRelationship) {
+    const args = ['brainbase', 'onboard:seed', '--dir', dataDir];
+    const append = (flag, value) => {
+        if (value)
+            args.push(flag, value);
+    };
+    append('--name', first(parsed, 'name'));
+    append('--value', first(parsed, 'value'));
+    append('--project', first(parsed, 'project'));
+    append('--decision-principle', first(parsed, 'decision-principle'));
+    for (const relationship of parsed.values.get('relationship') ?? []) {
+        if (relationship !== invalidRelationship)
+            append('--relationship', relationship);
+    }
+    append('--relationship', '田中|責任者|Atlas導入の最終判断を担当');
+    return args.map(shellArg).join(' ');
+}
 async function onboardInstall(parsed, io) {
     const target = first(parsed, 'target');
     if (!isInstallTarget(target)) {
@@ -239,9 +344,9 @@ async function onboardStart(parsed, io) {
         assumeGog: parsed.flags.has('assume-gog'),
         gogAvailable,
         project,
-        connected: status.connected === true,
+        connected: readLocalBackendConnected(status),
         missing
-    }, format));
+    }, format, parsed.flags.has('details')));
     return 0;
 }
 async function onboardDemo(parsed, io) {
@@ -249,8 +354,9 @@ async function onboardDemo(parsed, io) {
     const dataDir = resolveDataDir(first(parsed, 'dir'));
     await initializePersonalOs(dataDir);
     const os = await loadPersonalOs(dataDir);
-    write(io, renderValueDemo({ os, scenario: first(parsed, 'scenario') }, format));
-    return 0;
+    const demo = buildValueDemo({ os, scenario: first(parsed, 'scenario') });
+    write(io, renderValueDemo({ os, scenario: first(parsed, 'scenario') }, format, parsed.flags.has('details')));
+    return demo.ready ? 0 : 1;
 }
 async function onboardRecommend(parsed, io) {
     const format = parseOnboardingFormat(first(parsed, 'format'));
@@ -713,11 +819,35 @@ async function writeConfigSnippet(outputPath, payload) {
 async function doctor(parsed, io) {
     const dataDir = resolveDataDir(first(parsed, 'dir'));
     const os = await loadPersonalOs(dataDir);
-    write(io, `${JSON.stringify(onboardingStatus(os), null, 2)}\n`);
+    const status = onboardingStatus(os);
+    const judgmentHooksPath = first(parsed, 'judgment-hooks');
+    if (!judgmentHooksPath) {
+        write(io, `${JSON.stringify(status, null, 2)}\n`);
+        return 0;
+    }
+    const config = JSON.parse(await readFile(judgmentHooksPath, 'utf8'));
+    const hooks = config.hooks;
+    const requiredEvents = ['UserPromptSubmit', 'PostToolUse', 'Stop'];
+    const valid = Boolean(hooks) && requiredEvents.every((eventName) => {
+        const bindings = hooks?.[eventName];
+        return Array.isArray(bindings) && bindings.some((binding) => {
+            const commands = binding.hooks;
+            return Array.isArray(commands) && commands.some((command) => (typeof command.command === 'string'
+                && command.command.includes('judgment:hook')));
+        });
+    });
+    if (!valid)
+        throw new Error('judgment_hooks_invalid');
+    write(io, `${JSON.stringify({
+        ...status,
+        judgment_hooks: { status: 'ready', events: requiredEvents, source: judgmentHooksPath }
+    }, null, 2)}\n`);
     return 0;
 }
 function parseArgs(argv) {
-    const [command, ...rest] = argv;
+    const [firstToken, ...remaining] = argv;
+    const command = firstToken?.startsWith('--') ? undefined : firstToken;
+    const rest = command ? remaining : argv;
     const values = new Map();
     const flags = new Set();
     for (let index = 0; index < rest.length; index += 1) {
@@ -743,6 +873,13 @@ function parseArgs(argv) {
 function first(parsed, key) {
     return parsed.values.get(key)?.[0];
 }
+function readLocalBackendConnected(status) {
+    const localBackend = status.localBackend;
+    return typeof localBackend === 'object'
+        && localBackend !== null
+        && 'connected' in localBackend
+        && localBackend.connected === true;
+}
 async function commandExists(command) {
     const candidates = isAbsolute(command)
         ? [command]
@@ -758,15 +895,18 @@ async function commandExists(command) {
     }
     return false;
 }
-function upsertGraphEntity(entities, entity) {
-    const index = entities.findIndex((candidate) => candidate.id === entity.id);
+function upsertById(entries, entry) {
+    const index = entries.findIndex((candidate) => candidate.id === entry.id);
     if (index >= 0) {
-        entities[index] = entity;
+        entries[index] = entry;
     }
     else {
-        entities.push(entity);
+        entries.push(entry);
     }
 }
+function upsertGraphEntity(entities, entity) {
+    upsertById(entities, entity);
+}
 function hash(value) {
     let hashValue = 0;
     for (const char of value) {
@@ -794,15 +934,20 @@ function proposedPersonalOs(os, proposed) {
     return { ...os, ...proposed };
 }
 function usage() {
-    return `Usage:
+    return `最短で試す（3ステップ）:
+  1. brainbase onboard:start --target codex
+  2. 表示された brainbase onboard:seed を確認して実行
+  3. brainbase onboard:demo --scenario "実際に試す依頼"
+
+使い方:
   brainbase-mcp
   brainbase mcp
   brainbase onboard:init [--dir path]
   brainbase onboard:seed [--dir path] [--name value] [--value value] [--project value] [--decision-principle value] [--relationship "person|role|context"]
   brainbase onboard:install --target codex|claude|codecode [--dir path] [--dry-run] [--output path]
   brainbase onboard:agent [--format markdown|json]
-  brainbase onboard:start [--target codex|claude|codecode] [--dir path] [--name value] [--project value] [--goal value] [--status value] [--role value] [--email value] [--calendar value] [--drive value] [--drive-folder id] [--local-folder path] [--tasks value] [--format markdown|json]
-  brainbase onboard:demo [--dir path] [--scenario value] [--format markdown|json]
+  brainbase onboard:start [--target codex|claude|codecode] [--dir path] [--name value] [--value value] [--project value] [--decision-principle value] [--goal value] [--status value] [--role value] [--email value] [--calendar value] [--drive value] [--drive-folder id] [--local-folder path] [--tasks value] [--format markdown|json] [--details]
+  brainbase onboard:demo [--dir path] [--scenario value] [--format markdown|json] [--details]
   brainbase onboard:recommend [--email value] [--calendar value] [--drive value] [--tasks value] [--format markdown|json]
   brainbase onboard:diagnose-sources [--dir path] [--email value] [--calendar value] [--drive value] [--drive-folder id] [--tasks value] [--assume-gog] [--gog-command command] [--format markdown|json]
   brainbase onboard:plan [--profile google-workspace-local] [--host value] [--email value] [--secondary-email value] [--calendar value] [--drive value] [--drive-folder id] [--local-folder path] [--tasks value] [--inactive-task-tool value] [--format markdown|json]
@@ -815,10 +960,25 @@ function usage() {
   brainbase onboard:skills --target codex|claude|portable [--skills id,id] [--out dir] [--format markdown|json]
   brainbase ontology:show
   brainbase ontology:audit [--dir path] [--ontology-version 0.0.0|1.0.0]
-  brainbase doctor [--dir path]
+  brainbase judgment:install --target codex [--dry-run] [--output path]
+  brainbase judgment:hook
+  brainbase doctor [--dir path] [--judgment-hooks path]
 `;
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : JSON.stringify(value);
+}
+export function isCliEntrypoint(moduleUrl, invokedPath) {
+    if (!invokedPath)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(invokedPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint(import.meta.url, process.argv[1])) {
     const code = await runCli();
     process.exit(code);
 }

package/dist/connected-onboarding.d.ts

@@ -0,0 +1,123 @@
+declare const WORKFLOW_STATES: readonly ["initialized", "source_ready", "candidates_ready", "promotion_reviewed", "first_value_ready", "first_value_answer_reviewed"];
+export type SourceMode = 'mcp' | 'drive' | 'gmail' | 'local_folder' | 'single_document';
+export type SourceStatus = 'ready' | 'waiting_for_authorization' | 'unavailable' | 'error' | 'unconfirmed';
+export type ObservationClass = 'observed' | 'inferred';
+export type ReviewDecision = 'approve' | 'edit' | 'reject' | 'merge';
+export type WorkflowState = typeof WORKFLOW_STATES[number];
+export interface SourceInventoryInput {
+    id: string;
+    mode: SourceMode;
+    status: SourceStatus;
+    evidencePointer?: string;
+    permissionScope?: string[];
+    detail?: string;
+}
+export interface SourceInventory extends SourceInventoryInput {
+    id: string;
+    permissionScope: string[];
+}
+export interface SourceReceiptInput {
+    sourceId: string;
+    evidencePointer: string;
+    contentHash: string;
+    permissionSnapshot: Record<string, unknown>;
+    collectionStatus: 'collected';
+}
+export interface CandidateInput {
+    kind: string;
+    payload: Record<string, unknown>;
+    observationClass: ObservationClass;
+    evidenceId: string;
+}
+export interface ConnectedCandidate extends CandidateInput {
+    id: string;
+    ingestedPayloadHash: string;
+    sourceId: string;
+    reviewStatus: 'pending' | 'approved' | 'rejected' | 'merged';
+    reviewDecision?: ReviewDecision;
+    reviewReason?: string;
+    mergedIntoCandidateId?: string;
+    promotedCanonicalIds: string[];
+}
+export interface SourceReceipt extends SourceReceiptInput {
+    mode: SourceMode;
+    collectedAt: string;
+    candidateIds: string[];
+}
+export interface FirstValueReceipt {
+    answerHash: string;
+    usedCanonicalIds: string[];
+    missingContext: string[];
+    recordedAt: string;
+}
+export interface FirstValueReview {
+    verdict: 'useful' | 'not_useful';
+    missingContext: string[];
+    reviewedAt: string;
+    elapsedSeconds: number;
+    withinTargetSeconds: boolean;
+}
+export interface ConnectedOnboardingRun {
+    id: string;
+    valueTarget: string;
+    path: 'warm' | 'fallback' | 'blocked';
+    state: WorkflowState;
+    startedAt: string;
+    updatedAt: string;
+    sourceReadyAt?: string;
+    sources: SourceInventory[];
+    selectedSourceIds: string[];
+    receipts: SourceReceipt[];
+    candidates: ConnectedCandidate[];
+    promotedCanonicalIds: string[];
+    firstValueReceipt?: FirstValueReceipt;
+    firstValueReview?: FirstValueReview;
+}
+export interface ConnectedOnboardingOptions {
+    now?: () => Date;
+    idFactory?: () => string;
+}
+export interface ReviewAction {
+    candidateId: string;
+    decision: ReviewDecision;
+    reason: string;
+    payload?: Record<string, unknown>;
+    mergeIntoCandidateId?: string;
+}
+export type FirstValueInput = {
+    action: 'record';
+    answerHash: string;
+    usedCanonicalIds: string[];
+    missingContext?: string[];
+} | {
+    action: 'review';
+    verdict: 'useful' | 'not_useful';
+    missingContext?: string[];
+};
+export declare class ConnectedOnboardingError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ConnectedOnboardingRuntime {
+    private readonly dataDir;
+    private readonly now;
+    private readonly idFactory;
+    constructor(dataDir: string, options?: ConnectedOnboardingOptions);
+    start(input: {
+        valueTarget: string;
+        sources: SourceInventoryInput[];
+    }): Promise<ConnectedOnboardingRun>;
+    get(runId: string): Promise<ConnectedOnboardingRun>;
+    ingest(runId: string, input: {
+        source: SourceReceiptInput;
+        candidates: CandidateInput[];
+    }): Promise<ConnectedOnboardingRun>;
+    review(runId: string, actions: ReviewAction[]): Promise<ConnectedOnboardingRun>;
+    firstValue(runId: string, input: FirstValueInput): Promise<ConnectedOnboardingRun>;
+    private timestamp;
+    private readLedger;
+    private mutateLedger;
+}
+export declare function normalizeSourceInventory(raw: SourceInventoryInput[]): SourceInventory[];
+export declare function assertSafePersistentValue(value: unknown, trail?: string[]): void;
+export {};