@unson/brainbase-mcp 0.1.0 → 0.2.2

package/dist/server.js

@@ -2,6 +2,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { ConnectedOnboardingRuntime } from './connected-onboarding.js';
 import { resolveDataDir } from './paths.js';
 import { auditPersonalOsDirectory } from './ontology-ssot.js';
 import { getOntologyImpact, inferPersonalOs, portableOntology, resolveOntologyVersion } from './ontology.js';
@@ -16,6 +17,71 @@ const argsSchema = z.object({
     ontologyVersion: z.string().optional(),
     asOf: z.string().datetime({ offset: true }).optional()
 });
+const sourceInventorySchema = z.object({
+    id: z.string(),
+    mode: z.enum(['mcp', 'drive', 'gmail', 'local_folder', 'single_document']),
+    status: z.enum(['ready', 'waiting_for_authorization', 'unavailable', 'error', 'unconfirmed']),
+    evidencePointer: z.string().optional(),
+    permissionScope: z.array(z.string()).optional(),
+    detail: z.string().optional()
+}).strict();
+const candidateSchema = z.object({
+    kind: z.string(),
+    payload: z.record(z.unknown()),
+    observationClass: z.enum(['observed', 'inferred']),
+    evidenceId: z.string()
+}).strict();
+const reviewActionSchema = z.discriminatedUnion('decision', [
+    z.object({ candidateId: z.string(), decision: z.literal('approve'), reason: z.string() }).strict(),
+    z.object({ candidateId: z.string(), decision: z.literal('edit'), reason: z.string(), payload: z.record(z.unknown()) }).strict(),
+    z.object({ candidateId: z.string(), decision: z.literal('reject'), reason: z.string() }).strict(),
+    z.object({ candidateId: z.string(), decision: z.literal('merge'), reason: z.string(), mergeIntoCandidateId: z.string() }).strict()
+]);
+const connectedSchemas = {
+    brainbase_onboarding_start: z.object({
+        dataDir: z.string().optional(),
+        valueTarget: z.string(),
+        sources: z.array(sourceInventorySchema)
+    }).strict(),
+    brainbase_onboarding_get: z.object({ dataDir: z.string().optional(), runId: z.string() }).strict(),
+    brainbase_onboarding_ingest: z.object({
+        dataDir: z.string().optional(),
+        runId: z.string(),
+        source: z.object({
+            sourceId: z.string(),
+            evidencePointer: z.string(),
+            contentHash: z.string(),
+            permissionSnapshot: z.record(z.unknown()),
+            collectionStatus: z.literal('collected')
+        }).strict(),
+        candidates: z.array(candidateSchema)
+    }).strict(),
+    brainbase_onboarding_review: z.object({
+        dataDir: z.string().optional(),
+        runId: z.string(),
+        actions: z.array(reviewActionSchema)
+    }).strict(),
+    brainbase_onboarding_first_value: z.discriminatedUnion('action', [
+        z.object({
+            dataDir: z.string().optional(),
+            runId: z.string(),
+            action: z.literal('record'),
+            answerHash: z.string(),
+            usedCanonicalIds: z.array(z.string()),
+            verdict: z.enum(['useful', 'not_useful']).optional(),
+            missingContext: z.array(z.string()).optional()
+        }).strict(),
+        z.object({
+            dataDir: z.string().optional(),
+            runId: z.string(),
+            action: z.literal('review'),
+            answerHash: z.string().optional(),
+            usedCanonicalIds: z.array(z.string()).optional(),
+            verdict: z.enum(['useful', 'not_useful']),
+            missingContext: z.array(z.string()).optional()
+        }).strict()
+    ])
+};
 export const toolDefinitions = [
     {
         name: 'get_context',
@@ -40,7 +106,7 @@ export const toolDefinitions = [
     },
     {
         name: 'search',
-        description: 'Search canonical local Graph, Personal KG, relationships, and decisions.',
+        description: 'Search all canonical local stores: Graph entities, Personal KG, relationships, and decisions. Use this for people and projects.',
         inputSchema: {
             type: 'object',
             required: ['query'],
@@ -53,7 +119,7 @@ export const toolDefinitions = [
     },
     {
         name: 'search_personal_kg',
-        description: 'Search owner-local Personal KG only.',
+        description: 'Search owner-local Personal KG only. People and projects are Graph entities, so use search for them.',
         inputSchema: {
             type: 'object',
             required: ['query'],
@@ -74,9 +140,84 @@ export const toolDefinitions = [
             }
         }
     },
+    {
+        name: 'brainbase_onboarding_start',
+        description: 'Start a local first-value onboarding run from actually callable sources. The result exposes runId (also id); pass runId to every later onboarding tool.',
+        inputSchema: {
+            type: 'object', required: ['valueTarget', 'sources'], additionalProperties: false,
+            properties: {
+                dataDir: { type: 'string', description: 'Optional Personal OS directory.' }, valueTarget: { type: 'string', description: 'One concrete question the first useful answer should resolve.' },
+                sources: { type: 'array', maxItems: 50, items: { type: 'object', required: ['id', 'mode', 'status'], additionalProperties: false, properties: {
+                            id: { type: 'string' }, mode: { enum: ['mcp', 'drive', 'gmail', 'local_folder', 'single_document'] },
+                            status: { enum: ['ready', 'waiting_for_authorization', 'unavailable', 'error', 'unconfirmed'] }, evidencePointer: { type: 'string' },
+                            permissionScope: { type: 'array', items: { type: 'string' } }, detail: { type: 'string' }
+                        } } }
+            }
+        }
+    },
+    {
+        name: 'brainbase_onboarding_get',
+        description: 'Read a connected-world onboarding run without exposing source or answer bodies.',
+        inputSchema: { type: 'object', required: ['runId'], additionalProperties: false, properties: { dataDir: { type: 'string' }, runId: { type: 'string' } } }
+    },
+    {
+        name: 'brainbase_onboarding_ingest',
+        description: 'Ingest one selected source receipt under source plus review candidates. Do not flatten sourceId or receipt fields at the top level.',
+        inputSchema: {
+            type: 'object', required: ['runId', 'source', 'candidates'], additionalProperties: false,
+            properties: {
+                dataDir: { type: 'string' }, runId: { type: 'string', description: 'runId returned by brainbase_onboarding_start.' },
+                source: { type: 'object', required: ['sourceId', 'evidencePointer', 'contentHash', 'permissionSnapshot', 'collectionStatus'], additionalProperties: false, properties: {
+                        sourceId: { type: 'string' }, evidencePointer: { type: 'string' }, contentHash: { type: 'string' }, permissionSnapshot: { type: 'object' }, collectionStatus: { const: 'collected' }
+                    } },
+                candidates: { type: 'array', maxItems: 50, items: { type: 'object', required: ['kind', 'payload', 'observationClass', 'evidenceId'], additionalProperties: false, properties: {
+                            kind: { type: 'string' }, payload: { type: 'object' }, observationClass: { enum: ['observed', 'inferred'] }, evidenceId: { type: 'string' }
+                        } } }
+            }
+        }
+    },
+    {
+        name: 'brainbase_onboarding_review',
+        description: 'Submit review decisions in actions. Inferred candidates cannot be approved or merged; use edit with a human-confirmed payload, or reject.',
+        inputSchema: {
+            type: 'object', required: ['runId', 'actions'], additionalProperties: false,
+            properties: { dataDir: { type: 'string' }, runId: { type: 'string', minLength: 1, maxLength: 200 }, actions: { type: 'array', minItems: 1, maxItems: 50, items: {
+                        oneOf: [
+                            { type: 'object', required: ['candidateId', 'decision', 'reason'], additionalProperties: false, properties: {
+                                    candidateId: { type: 'string', minLength: 1, maxLength: 200 }, decision: { const: 'approve' }, reason: { type: 'string', minLength: 1, maxLength: 500 }
+                                } },
+                            { type: 'object', required: ['candidateId', 'decision', 'reason', 'payload'], additionalProperties: false, properties: {
+                                    candidateId: { type: 'string', minLength: 1, maxLength: 200 }, decision: { const: 'edit' }, reason: { type: 'string', minLength: 1, maxLength: 500 }, payload: { type: 'object' }
+                                } },
+                            { type: 'object', required: ['candidateId', 'decision', 'reason'], additionalProperties: false, properties: {
+                                    candidateId: { type: 'string', minLength: 1, maxLength: 200 }, decision: { const: 'reject' }, reason: { type: 'string', minLength: 1, maxLength: 500 }
+                                } },
+                            { type: 'object', required: ['candidateId', 'decision', 'reason', 'mergeIntoCandidateId'], additionalProperties: false, properties: {
+                                    candidateId: { type: 'string', minLength: 1, maxLength: 200 }, decision: { const: 'merge' }, reason: { type: 'string', minLength: 1, maxLength: 500 }, mergeIntoCandidateId: { type: 'string', minLength: 1, maxLength: 200 }
+                                } }
+                        ]
+                    } } }
+        }
+    },
+    {
+        name: 'brainbase_onboarding_first_value',
+        description: 'Finish onboarding in two calls. First choose action=record with an answer hash and promoted canonical IDs. Then choose action=review with useful or not_useful.',
+        inputSchema: {
+            type: 'object', required: ['runId', 'action'], additionalProperties: false,
+            properties: {
+                dataDir: { type: 'string', description: 'Optional Personal OS directory.' },
+                runId: { type: 'string', minLength: 1, maxLength: 200, description: 'runId returned by the previous onboarding step.' },
+                action: { enum: ['record', 'review'], description: 'Use record first. Use review only after the answer receipt has been recorded.' },
+                answerHash: { type: 'string', pattern: '^sha256:[a-f0-9]{64}$', description: 'Required for action=record. SHA-256 of the answer body; the body itself is not stored.' },
+                usedCanonicalIds: { type: 'array', minItems: 1, maxItems: 50, items: { type: 'string', minLength: 1, maxLength: 200 }, description: 'Required for action=record. Use only promotedCanonicalIds returned by review.' },
+                verdict: { enum: ['useful', 'not_useful'], description: 'Required for action=review.' },
+                missingContext: { type: 'array', maxItems: 50, items: { type: 'string', minLength: 1, maxLength: 200 }, description: 'Optional short labels for context the answer still lacked.' }
+            }
+        }
+    },
     {
         name: 'get_ontology',
-        description: 'Return the bundled immutable Brainbase Portable Ontology Kernel release.',
+        description: 'Return a beginner guide followed by the bundled immutable Brainbase Portable Ontology Kernel release.',
         inputSchema: {
             type: 'object',
             properties: {}
@@ -117,11 +258,63 @@ export const toolDefinitions = [
     }
 ];
 export async function callBrainbaseTool(name, rawArgs = {}) {
+    if (name in connectedSchemas) {
+        return callConnectedOnboardingTool(name, rawArgs);
+    }
     const args = argsSchema.parse(rawArgs ?? {});
     const dataDir = resolveDataDir(args.dataDir);
     switch (name) {
         case 'get_ontology':
-            return portableOntology;
+            return {
+                beginnerGuide: {
+                    startHere: 'まずここだけ読めば大丈夫です。下の業務例から全体像をつかみ、必要なときだけ正式契約を確認してください。',
+                    oneSentence: 'オントロジーは、仕事の言葉・つながり・守る条件・判断方法・変更履歴を、Brainbaseと人が同じ意味で扱うための約束です。',
+                    workExample: '例: 「新しい方針が旧方針を置き換えた」と登録すると、Brainbaseは新しい方針を現在有効な判断として扱い、旧方針も履歴として残します。',
+                    fiveParts: [
+                        { id: 'types', name: '種類', question: 'これは何ですか？', example: '人、組織、プロジェクト、関係、意思決定' },
+                        { id: 'relations', name: '関係', question: '何とどうつながっていますか？', example: '新しい意思決定が旧意思決定を置き換える' },
+                        { id: 'constraints', name: '必須条件', question: '登録前に何が揃っている必要がありますか？', example: '置き換える相手の意思決定が実在する' },
+                        { id: 'inference', name: '判断規則', question: '明示した事実から何を判断しますか？', example: '置き換えられた旧意思決定は現在有効ではない' },
+                        { id: 'evolution', name: '変更履歴', question: '履歴を失わずに意味をどう変えますか？', example: '監査して新しい版へ移行し、戻し方も残す' }
+                    ],
+                    changeSafety: {
+                        check: '変更前は ontology_impact で影響を確認し、audit_ontology で現在の不整合を調べます。',
+                        recover: '誤った定義は履歴を消さず、新しい版で訂正し、移行と戻し方を記録します。'
+                    },
+                    unsafeShortcuts: [
+                        {
+                            request: '旧方針や変更履歴を削除して最新版だけにする',
+                            handling: 'reject_and_explain',
+                            safeAlternative: '履歴は削除せず、新しい版を作り、supersedes と有効日を記録して置き換えます。'
+                        },
+                        {
+                            request: '影響確認や監査を完了扱いにして先へ進む',
+                            handling: 'reject_and_explain',
+                            safeAlternative: 'ontology_impact と audit_ontology の実行結果を確認してから完了とします。'
+                        },
+                        {
+                            request: '必須項目を空欄のまま自動で補って登録する',
+                            handling: 'reject_and_explain',
+                            safeAlternative: '不足項目を明示し、根拠を確認できるまで登録せず候補として残します。'
+                        }
+                    ],
+                    toolChooser: [
+                        { goal: '変更の影響を知りたい', tool: 'ontology_impact', when: '定義や関係を変える前に実行します。' },
+                        { goal: '現在の不整合を調べたい', tool: 'audit_ontology', when: '変更前の現状確認と、変更後の再確認に使います。' },
+                        { goal: '現在有効な判断を知りたい', tool: 'infer_decisions', when: '旧判断を除き、今使う判断を確かめるときに使います。' }
+                    ],
+                    changeChecklist: [
+                        '変更前: ontology_impact で影響を確認する。',
+                        '変更前: audit_ontology で現在の不整合を確認する。',
+                        '変更時: 旧版を消さず、新版に supersedes と有効日を記録する。',
+                        '変更後: audit_ontology の実行結果を確認し、未実行なら完了扱いにしない。',
+                        '問題時: 履歴を残したまま訂正版と戻し方を記録する。'
+                    ],
+                    detailsNotice: '以下の正式契約は、実装・監査・詳しい確認が必要なときに読みます。',
+                    suggestedNextTools: ['audit_ontology', 'infer_decisions', 'ontology_impact']
+                },
+                ...portableOntology
+            };
         case 'audit_ontology':
             return auditPersonalOsDirectory(dataDir, { ontologyVersion: resolveOntologyVersion(args.ontologyVersion) });
         case 'ontology_impact':
@@ -154,6 +347,143 @@ export async function callBrainbaseTool(name, rawArgs = {}) {
             throw new Error(`Unknown tool: ${name}`);
     }
 }
+async function callConnectedOnboardingTool(name, rawArgs) {
+    const schema = connectedSchemas[name];
+    const args = schema.parse(rawArgs ?? {});
+    const runtime = new ConnectedOnboardingRuntime(resolveDataDir(args.dataDir));
+    switch (name) {
+        case 'brainbase_onboarding_start':
+            return runtime.start(args)
+                .then(withOnboardingGuidance);
+        case 'brainbase_onboarding_get':
+            return runtime.get(args.runId).then(withOnboardingGuidance);
+        case 'brainbase_onboarding_ingest': {
+            const { runId, dataDir: _dataDir, ...input } = args;
+            return runtime.ingest(runId, input).then(withOnboardingGuidance);
+        }
+        case 'brainbase_onboarding_review':
+            return runtime.review(args.runId, args.actions).then(withOnboardingGuidance);
+        case 'brainbase_onboarding_first_value': {
+            const input = args.action === 'record'
+                ? {
+                    action: 'record',
+                    answerHash: args.answerHash,
+                    usedCanonicalIds: args.usedCanonicalIds,
+                    missingContext: args.missingContext
+                }
+                : {
+                    action: 'review',
+                    verdict: args.verdict,
+                    missingContext: args.missingContext
+                };
+            return runtime.firstValue(args.runId, input).then(withOnboardingGuidance);
+        }
+    }
+}
+function withOnboardingGuidance(run) {
+    const pendingCandidateIds = run.candidates
+        .filter((candidate) => candidate.reviewStatus === 'pending')
+        .map((candidate) => candidate.id);
+    const nextAction = (() => {
+        switch (run.state) {
+            case 'initialized':
+                return onboardingAction('brainbase_onboarding_start', '利用できる情報源を準備する', '利用を許可するか、読み取れる情報源を追加して、新しいオンボーディングを開始します。', [], '新しい実行を作成します。既存データは変更しません。', true, '準備できない場合は開始せず、情報源の設定に戻れます。');
+            case 'source_ready':
+                return onboardingAction('brainbase_onboarding_ingest', '準備できた情報源を取り込む', '選択済みの情報源から、証拠の記録と確認候補を取り込みます。', run.selectedSourceIds, '確認待ちの候補を作ります。まだ正式な情報にはなりません。', true, '取り込み後も、候補を却下すれば正式な情報には反映されません。');
+            case 'candidates_ready':
+                return onboardingAction('brainbase_onboarding_review', '候補を確認する', 'すべての候補を確認します。推測された候補は、人が確認した内容へ edit するか、reject で却下してください。', pendingCandidateIds, '確認した候補だけを正式な情報として登録します。', true, '確信がなければ却下できます。誤って登録した場合も履歴を残して訂正できます。');
+            case 'promotion_reviewed':
+                return onboardingAction('brainbase_onboarding_first_value', '最初の回答を記録する', 'action=record と回答の answerHash、登録済みIDを使って、回答の記録だけを保存します。', run.promotedCanonicalIds, '回答本文ではなくハッシュと使用したIDを記録します。', true, '回答本文は保存されません。記録後に役立ったかを確認できます。');
+            case 'first_value_ready':
+                return onboardingAction('brainbase_onboarding_first_value', '回答が役立ったか評価する', 'action=review と verdict=useful または not_useful を使って評価します。', [], '最初の回答に対する評価を記録し、オンボーディングを完了します。', true, '役立たなかった場合は not_useful と不足情報を記録できます。');
+            case 'first_value_answer_reviewed':
+                return null;
+        }
+    })();
+    const baseGuide = onboardingGuide(run.state);
+    const safetyBoundaries = {
+        mode: 'mandatory',
+        review: '候補の全件自動承認や確認の省略は行いません。候補ごとに根拠を確認し、承認・編集・却下を選びます。',
+        resume: `中断後は同じ runId ${run.id} を取得し、表示された次の操作だけを続けます。`,
+        completion: '完了済みの操作は再実行しません。現在の状態と残りの操作を確認してから続けます。'
+    };
+    const guardedNextAction = nextAction === null ? null : {
+        ...nextAction,
+        inputHelp: onboardingInputHelp(run),
+        confirmation: {
+            ...nextAction.confirmation,
+            cannotSkip: '確認の省略や全件自動承認はできません。必要なIDごとに内容と根拠を確認してください。',
+            resumeRule: `同じ runId ${run.id} で現在状態を取得し、完了済みの操作は繰り返さず、この操作だけを実行します。`
+        }
+    };
+    const guide = {
+        ...baseGuide,
+        plainText: guardedNextAction === null
+            ? `${baseGuide.current} 残りの操作はありません。runIdは${run.id}です。完了済み操作は繰り返しません。`
+            : `${baseGuide.current} 次は「${guardedNextAction.label}」だけを行います。runIdは${run.id}です。${baseGuide.remaining}`
+    };
+    return { guide, nextAction: guardedNextAction, safetyBoundaries, ...run, runId: run.id };
+}
+function onboardingInputHelp(run) {
+    switch (run.state) {
+        case 'initialized':
+            return [{ field: 'sources', meaning: '利用を許可する情報源', source: '準備済みまたは許可待ちの情報源一覧から選びます。' }];
+        case 'source_ready':
+            return [{ field: 'sourceId', meaning: '今回取り込む情報源', source: 'nextAction.requiredIds に表示されたIDを使います。' }];
+        case 'candidates_ready':
+            return [
+                { field: 'candidateId', meaning: '確認する候補', source: 'nextAction.requiredIds に表示されたIDを一件ずつ使います。' },
+                { field: 'decision', meaning: '確認結果', source: '内容を確認して edit、確信がなければ reject を選びます。' }
+            ];
+        case 'promotion_reviewed':
+            return [
+                { field: 'answerHash', meaning: '回答本文を保存せず同じ回答を識別する値', source: '直前に作った回答からエージェントが生成し、利用者は対象回答だけ確認します。' },
+                { field: 'usedCanonicalIds', meaning: '回答で使った正式情報', source: '直前の promotedCanonicalIds から、実際に回答で使ったIDを選びます。' }
+            ];
+        case 'first_value_ready':
+            return [{ field: 'verdict', meaning: '回答が役立ったか', source: '利用者が useful または not_useful を選びます。' }];
+        case 'first_value_answer_reviewed':
+            return [];
+    }
+}
+function onboardingAction(tool, label, instruction, requiredIds, changes, reversible, recovery) {
+    return { tool, label, instruction, requiredIds, confirmation: { changes, reversible, recovery } };
+}
+function onboardingGuide(state) {
+    const guides = {
+        initialized: {
+            current: '利用できる情報源を準備する段階です。',
+            completed: [],
+            remaining: '情報源の準備、取り込み、候補の確認、最初の回答の評価が残っています。'
+        },
+        source_ready: {
+            current: '利用する情報源を選びました。',
+            completed: ['情報源の選択'],
+            remaining: '情報の取り込み、候補の確認、最初の回答の評価が残っています。'
+        },
+        candidates_ready: {
+            current: '取り込んだ候補を確認する段階です。',
+            completed: ['情報源の選択', '情報の取り込み'],
+            remaining: '候補の確認、最初の回答の記録と評価が残っています。'
+        },
+        promotion_reviewed: {
+            current: '確認済みの候補を正式な情報として登録しました。',
+            completed: ['情報源の選択', '情報の取り込み', '候補の確認'],
+            remaining: '最初の回答の記録と評価が残っています。'
+        },
+        first_value_ready: {
+            current: '最初の回答を記録しました。',
+            completed: ['情報源の選択', '情報の取り込み', '候補の確認', '最初の回答の記録'],
+            remaining: '回答が役立ったかの評価が残っています。'
+        },
+        first_value_answer_reviewed: {
+            current: '最初の回答の評価まで完了しました。',
+            completed: ['情報源の選択', '情報の取り込み', '候補の確認', '最初の回答の記録', '回答の評価'],
+            remaining: 'ありません。'
+        }
+    };
+    return guides[state];
+}
 export function createServer() {
     const server = new Server({
         name: 'brainbase-mcp',

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 export type SkillTarget = 'codex' | 'claude' | 'portable';
-export type BrainbaseSkillId = 'brainbase-personal-onboarding' | 'brainbase-source-import' | 'brainbase-candidate-review' | 'brainbase-daily-routines';
+export type BrainbaseSkillId = 'brainbase-personal-onboarding' | 'brainbase-connected-world-onboarding' | 'brainbase-source-import' | 'brainbase-candidate-review' | 'brainbase-daily-routines';
 export interface BrainbaseSkillDefinition {
     id: BrainbaseSkillId;
     title: string;

package/dist/skills.js

@@ -1,5 +1,6 @@
 export const ALL_BRAINBASE_SKILLS = [
     'brainbase-personal-onboarding',
+    'brainbase-connected-world-onboarding',
     'brainbase-source-import',
     'brainbase-candidate-review',
     'brainbase-daily-routines'
@@ -22,20 +23,53 @@ const SKILL_DEFINITIONS = {
             '',
             '## 手順',
             '',
-            '1. 最初に `brainbase onboard:agent` を実行し、メール、カレンダー、ドライブ/ドキュメント、タスク、権限、承認についてエージェントに確認させる。',
-            '2. `brainbase onboard:init` でローカルPersonal OSディレクトリを作成する。',
-            '3. ソースデータを集める前に、ユーザーの回答を使って `brainbase onboard:diagnose-sources` を実行する。',
-            '4. `brainbase onboard:projects` で、現在のプロジェクト名、目的、状態、役割、関係者、許可されたソースをレビュー可能な形にする。',
-            '5. `brainbase onboard:candidates --write`、またはsource import/extractの流れでレビュー候補を作る。',
-            '6. ユーザーが明示的に承認した事実だけを `brainbase onboard:seed`、`brainbase onboard:projects --write`、または `brainbase onboard:apply --write` でcanonical SSOTへ昇格する。',
-            '7. `brainbase onboard:install --target codex|claude|codecode --dry-run` でMCP設定スニペットを生成し、ユーザーに確認してもらう。',
+            '1. 最初に、Brainbaseを使って試したい現実の依頼を一つ聞く。',
+            '2. `brainbase onboard:start --target codex|claude|codecode` を実行し、本人、プロジェクト、関係者、判断基準の最小候補を確認する。',
+            '3. ユーザーが明示的に承認した事実だけを `brainbase onboard:seed` で保存する。',
+            '4. `brainbase onboard:install --target codex|claude|codecode --dry-run` でMCP設定を確認し、承認後に実設定へ反映して対象エージェントを再起動する。',
+            '5. 新しい実際のエージェントで、Brainbaseの `get_context` と `search` を使うよう明示して最初の現実の依頼を実行する。',
+            '6. 実回答、使われた保存済み文脈、未確認事項をユーザーへ示し、本人に役立ったかを確認する。ここまでを10分以内の初回価値候補ジャーニーとして測る。',
+            '7. CLIの `onboard:demo` は必要なら接続前のプレビューに使えるが、CLIサンプルは初回価値の達成証拠にしない。',
+            '8. 本人が役立つと確認した後だけ、必要に応じてsource診断、追加候補、Skills、ルーティンへ進む。',
+            '9. 継続利用するプロジェクトの詳細が必要なら、本人確認後に `brainbase onboard:projects --write` で登録する。',
             '',
             '## 安全ルール',
             '',
             `- ${SECRET_RULE}`,
             '- Brainbaseはローカルファーストで扱う。ユーザーが別のローカルパスを明示しない限り、ローカルMCPサーバーと `~/.brainbase/personal-os/` を使う。',
             '- メール、カレンダー、ドライブ、タスク、メモの生データは `sources/` 配下の二次材料として扱う。',
-            '- canonical contextは、ユーザー確認後の `graph.json`、`relationships.json`、`personal-kg.jsonl`、`decisions.jsonl` だけから作る。'
+            '- canonical contextは、ユーザー確認後の `graph.json`、`relationships.json`、`personal-kg.jsonl`、`decisions.jsonl` だけから作る。',
+            '- 終了コード0、`ready: true`、CLIサンプル、合成ペルソナ判定を、人間本人の価値認識に置き換えない。'
+        ].join('\n')
+    },
+    'brainbase-connected-world-onboarding': {
+        id: 'brainbase-connected-world-onboarding',
+        title: 'Brainbase接続済み世界オンボーディング',
+        description: '実際に呼び出せる仕事ソースを棚卸しし、承認済み事実だけで最初の価値まで進める。',
+        body: [
+            '## 目的',
+            '',
+            '既に接続できる仕事ソースから、最小範囲の証拠を人間レビューへつなぎ、10分以内に最初の価値を評価する。',
+            '',
+            '## 手順',
+            '',
+            '1. 最初に「Brainbaseで最初に何が分かると価値があるか」を一つ聞く。',
+            '2. 自分が実際に呼び出せるMCP、Drive、Gmailを確認する。ローカルはユーザーが明示した限定フォルダ、fallbackは明示された単一ドキュメントだけを対象にする。',
+            '3. 各sourceを `ready`、`waiting_for_authorization`、`unavailable`、`error`、`unconfirmed` に分ける。認証失敗、timeout、未確認を0件やreadyにしない。',
+            '4. 最初の価値とsource inventoryを `brainbase_onboarding_start` に渡し、返された `selectedSourceIds` だけを使う。',
+            '5. selected sourceをmetadata-firstで最小範囲だけ取得し、本文ではなくpointer、SHA-256 hash、permission snapshotと短い構造化候補を `brainbase_onboarding_ingest` に渡す。',
+            '6. `brainbase_onboarding_get` の候補を、要約・evidence ID・observed/inferred区分付きでユーザーへ示す。',
+            '7. ユーザーの判断を `brainbase_onboarding_review` の `approve`、`edit`、`reject`、`merge` とreasonで記録する。inferred候補はapproveせず、確認できた内容へeditするかrejectする。',
+            '8. 昇格済みcanonical IDだけで最初の回答を作る。回答本文を渡さず、hashと使用IDを `brainbase_onboarding_first_value` の `record` で記録する。',
+            '9. ユーザーへ役立ったかを聞き、`useful` または `not_useful` と不足文脈を同toolの `review` で記録する。',
+            '',
+            '## 安全ルール',
+            '',
+            `- ${SECRET_RULE}`,
+            '- 全Drive、全mailbox、home directory全体を走査しない。selected sourceのpermission scopeを越えない。',
+            '- source本文と回答本文をBrainbase onboarding ledgerへ保存しない。',
+            '- 候補はcanonical memoryではない。人間が明示的にreviewしたobserved factだけを昇格する。',
+            '- connectorが使えない時は状態をそのまま報告し、別sourceまたは明示された単一ドキュメントを提案する。'
         ].join('\n')
     },
     'brainbase-source-import': {

package/dist/ssot.d.ts

@@ -2,3 +2,12 @@ import type { PersonalOs } from './types.js';
 export declare function initializePersonalOs(dataDir: string): Promise<void>;
 export declare function loadPersonalOs(dataDir: string): Promise<PersonalOs>;
 export declare function mutatePersonalOs(dataDir: string, mutator: (current: PersonalOs) => PersonalOs | Promise<PersonalOs>): Promise<PersonalOs>;
+export declare function mutatePersonalOsWithSidecar<T>(dataDir: string, sidecarPath: string, mutator: (current: PersonalOs) => {
+    next: PersonalOs;
+    sidecarContent: string;
+    result: T;
+} | Promise<{
+    next: PersonalOs;
+    sidecarContent: string;
+    result: T;
+}>): Promise<T>;

package/dist/ssot.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { hostname } from 'node:os';
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
 import { z } from 'zod';
 import { assertOntologyValid } from './ontology.js';
 import { emptyGraph, emptyRelationships, schemaTemplates } from './templates.js';
@@ -99,6 +99,19 @@ export async function mutatePersonalOs(dataDir, mutator) {
         return normalized;
     });
 }
+export async function mutatePersonalOsWithSidecar(dataDir, sidecarPath, mutator) {
+    assertSafeSidecarPath(sidecarPath);
+    return withSsotLock(dataDir, async () => {
+        await recoverTransactions(dataDir);
+        assertCompleteCanonicalSet(dataDir, await canonicalPresence(dataDir));
+        const current = await loadPersonalOsUnlocked(dataDir);
+        const mutation = await mutator(current);
+        const normalized = { ...mutation.next, dataDir, sourceCount: current.sourceCount };
+        validateAggregate(normalized);
+        await commitAggregate(dataDir, normalized, 'mutation', [{ relativePath: sidecarPath, content: mutation.sidecarContent }]);
+        return mutation.result;
+    });
+}
 async function loadPersonalOsUnlocked(dataDir) {
     const graph = graphSchema.parse(await readJson(join(dataDir, 'graph.json')));
     const relationships = relationshipsSchema.parse(await readJson(join(dataDir, 'relationships.json')));
@@ -107,7 +120,7 @@ async function loadPersonalOsUnlocked(dataDir) {
     const sourceCount = await countSources(dataDir);
     return { dataDir, graph, personalKg, relationships, decisions, sourceCount };
 }
-async function commitAggregate(dataDir, next, mode) {
+async function commitAggregate(dataDir, next, mode, sidecars = []) {
     validateAggregate(next);
     const id = randomUUID();
     const stagingDir = join(dataDir, `${stagingPrefix}${id}`);
@@ -116,16 +129,25 @@ async function commitAggregate(dataDir, next, mode) {
     const previousDir = join(stagingDir, 'previous');
     await mkdir(nextDir, { recursive: true });
     await writeAggregate(nextDir, next);
+    for (const sidecar of sidecars) {
+        assertSafeSidecarPath(sidecar.relativePath);
+        await mkdir(dirname(join(nextDir, sidecar.relativePath)), { recursive: true });
+        await writeFile(join(nextDir, sidecar.relativePath), sidecar.content, { mode: 0o600 });
+    }
     if (mode === 'mutation') {
         await mkdir(previousDir, { recursive: true });
         await copyCanonicalSet(dataDir, previousDir);
+        for (const sidecar of sidecars) {
+            await mkdir(dirname(join(previousDir, sidecar.relativePath)), { recursive: true });
+            await copyFile(join(dataDir, sidecar.relativePath), join(previousDir, sidecar.relativePath));
+        }
     }
-    const metadata = { version: 1, mode };
+    const metadata = { version: 1, mode, ...(sidecars.length > 0 ? { sidecarFiles: sidecars.map((item) => item.relativePath) } : {}) };
     await writeFile(join(stagingDir, 'transaction.json'), `${JSON.stringify(metadata, null, 2)}\n`);
     await writeFile(join(stagingDir, 'PREPARED'), '');
     await rename(stagingDir, transactionDir);
     try {
-        await publishCanonicalSet(dataDir, join(transactionDir, 'next'), id, true);
+        await publishCanonicalSet(dataDir, join(transactionDir, 'next'), id, true, metadata.sidecarFiles ?? []);
         await writeFile(join(transactionDir, 'COMMITTED'), '');
     }
     catch (error) {
@@ -168,10 +190,10 @@ async function recoverTransaction(dataDir, transactionDir) {
     if (process.env.BRAINBASE_SSOT_FAIL_RECOVERY === '1') {
         throw new Error(`Injected SSOT transaction recovery failure for ${transactionDir}`);
     }
-    await publishCanonicalSet(dataDir, retainedDir, `recovery-${randomUUID()}`, false);
+    await publishCanonicalSet(dataDir, retainedDir, `recovery-${randomUUID()}`, false, metadata.sidecarFiles ?? []);
     await rm(transactionDir, { recursive: true, force: true });
 }
-async function publishCanonicalSet(dataDir, retainedDir, token, allowInjectedFailure) {
+async function publishCanonicalSet(dataDir, retainedDir, token, allowInjectedFailure, sidecarFiles = []) {
     let published = 0;
     const failAfter = Number.parseInt(process.env.BRAINBASE_SSOT_FAIL_AFTER_PUBLISH ?? '', 10);
     const pauseAfterPublishMs = parsePositiveInteger(process.env.BRAINBASE_SSOT_PAUSE_AFTER_PUBLISH_MS, 0);
@@ -187,6 +209,18 @@ async function publishCanonicalSet(dataDir, retainedDir, token, allowInjectedFai
             throw new Error(`Injected SSOT publish failure after ${published} file(s)`);
         }
     }
+    for (const relativePath of sidecarFiles) {
+        assertSafeSidecarPath(relativePath);
+        const target = join(dataDir, relativePath);
+        await mkdir(dirname(target), { recursive: true });
+        const temporary = `${target}-${token}.tmp`;
+        await copyFile(join(retainedDir, relativePath), temporary);
+        await rename(temporary, target);
+        published += 1;
+        if (allowInjectedFailure && Number.isFinite(failAfter) && published === failAfter) {
+            throw new Error(`Injected SSOT publish failure after ${published} file(s)`);
+        }
+    }
 }
 async function writeAggregate(targetDir, os) {
     await writeFile(join(targetDir, 'graph.json'), `${JSON.stringify(os.graph, null, 2)}\n`);
@@ -318,8 +352,34 @@ async function readTransactionMetadata(transactionDir) {
     if (value.version !== 1 || (value.mode !== 'initialization' && value.mode !== 'mutation')) {
         throw new Error(`Invalid registered SSOT transaction metadata in ${transactionDir}`);
     }
+    if (value.sidecarFiles !== undefined && (!Array.isArray(value.sidecarFiles) || value.sidecarFiles.some((path) => typeof path !== 'string'))) {
+        throw new Error(`Invalid registered SSOT transaction sidecars in ${transactionDir}`);
+    }
+    for (const path of value.sidecarFiles ?? [])
+        assertSafeSidecarPath(path);
     return value;
 }
+function assertSafeSidecarPath(relativePath) {
+    const resolvedRoot = resolve('.');
+    const resolvedPath = resolve(resolvedRoot, relativePath);
+    const containment = relative(resolvedRoot, resolvedPath);
+    const caseFoldedPath = relativePath.toLocaleLowerCase('en-US');
+    const topLevel = caseFoldedPath.split('/')[0];
+    const collidesWithManagedPath = canonicalFiles.includes(caseFoldedPath)
+        || topLevel === lockName.toLocaleLowerCase('en-US')
+        || topLevel.startsWith(stagingPrefix.toLocaleLowerCase('en-US'))
+        || topLevel.startsWith(transactionPrefix.toLocaleLowerCase('en-US'));
+    if (!relativePath
+        || relativePath.includes('\\')
+        || isAbsolute(relativePath)
+        || win32.isAbsolute(relativePath)
+        || containment === '..'
+        || containment.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)
+        || relativePath.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+        || collidesWithManagedPath) {
+        throw new Error(`Unsafe SSOT transaction sidecar path: ${relativePath}`);
+    }
+}
 async function exists(path) {
     try {
         await access(path, constants.F_OK);